Sugar Labs - User contributions [en]

Development Team/Low-level Activity API

2012-06-05T15:25:33Z

Bert: /* External Media */ media -> volumes

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
<strike>
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).
</strike>

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data. Use the [[#External Media|external media API]] instead.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external volumes directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

Depending on the Linux distro version, the volumes appear as /mnt/*, /media/*, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

<strike>
==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

</strike>

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T15:23:41Z

Bert: /* Mount Points */ reformatting

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
<strike>
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).
</strike>

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data. Use the [[#External Media|external media API]] instead.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external media directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

Depending on the Linux distro version, the volumes appear as /mnt/*, /media/*, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

<strike>
==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

</strike>

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T15:18:06Z

Bert: /* Presence */ presence service has been deprecated. strike out documentation.

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
<strike>Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point</strike> (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external media directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

Depending on the Linux distro version, the volumes appear as /mnt/*, /media/*, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

<strike>
==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

</strike>

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T15:03:24Z

Bert: /* External Media */ Recommend to use GIO to find volumes, not the deprecated mount points API

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
<strike>Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point</strike> (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal. No access restrictions are applied currently. If activities use these external media directly, they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

Depending on the Linux distro version, the volumes appear as /mnt/*, /media/*, /run/media/$USER/*, or in other places. Sugar up to version 0.82 provided an API to access their [[#Mount Points|mount points]]. Nowadays you should use general Linux API to find the volumes. The recommended way is using the [http://developer.gnome.org/gio/stable/GVolumeMonitor.html GNOME Volume Monitor] with a fallback to [http://www.freedesktop.org/wiki/Software/hal HAL] (there is an example in the [http://git.sugarlabs.org/backup/mainline/blobs/master/backup.py#line671 Backup activity]).

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T14:41:02Z

Bert: /* Mount Points */ strike out

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
<strike>Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point</strike> (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T14:38:47Z

Bert: /* Querying */ strike out mount points

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', <strike>the mountpoint of the item at key 'mountpoint',</strike> and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: <strike>'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified) </strike>
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T14:27:29Z

Bert: /* Focusing Objects */ mention full file path

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the "detail view" of the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file, then call ShowObject() on it).

Note: since Sugar 0.84, you also can give the full path to an existing file instead of an object id. If the user resumes that file, it will be copied to the Journal first and the opened using the chosen activity. This seems to be of limited usefulness and is documented here just for completeness

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-05T08:17:28Z

Bert: /* Choosing Objects */ remove utf8 encoding - paths are just bytes

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is an absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2012-06-04T21:17:19Z

Bert: /* Choosing Objects */ object_idobject_id_or_path:s

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):

chooser_id = org.laptop.Journal.ChooseObject(xid:s, what_filter:s) # in Sugar 0.82 this had only one argument

The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch the following signals which get emitted when an item is chosen or the dialog is cancelled:

ObjectChooserResponse(chooser_id:s, object_id_or_path:s)
ObjectChooserCancelled(chooser_id:s)

The chooser_id can be tested to see if this signal was in response to our own request. This is important if the user opens two file choosers at the same time (possibly in two different activities). If the user closes the chooser without selecting anything, the ObjectChooserCancelled signal is sent. Otherwise, the ObjectChooserResponse signal will be sent, and its object_id_or_path string argument is either an object id or a file path. To distinguish between the two cases, check if the first character is a slash (<tt>'/'</tt>). If it indeed begins with a slash, then this is a utf8-encoded absolute path to a file, which can be opened directly. Otherwise, if the first character is not a slash, then object_id_or_path is an object id, which can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

0.96/Notes

2012-05-22T10:41:34Z

Bert: /* Etoys */ link to new features section in release notes

<noinclude>{{ Translations | [[0.94/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]

''Please do not edit unless you are part of the Sugar Release Team. Comments are welcome on the [[{{TALKPAGENAME}}|Discussion page]].''

Sucrose 0.96 Release Notes

== Introduction ==
Sugar 0.96 is the new version of the [http://www.sugarlabs.org/ Sugar learning platform]. It was released the 30th of April 2012 (see [[0.96/Roadmap#Schedule]] for details).

The main changes in this cycle was the introduction of the new sugar-toolkit-gtk3 which is the sugar-toolkit ported to use GTK+ 3 and Pygobject3. Currently Browse, Read, the HellowWorld activity and Abacus have been ported to the new toolkit.

[[File:0.96 Read.png|640px]]

The Read activity has been ported to use the new toolkit.

[[File:0.96 browse.png|640px]]

Besides moving to the new toolkit Browse and related components have been switching to WebKit as its back-end technology.

== What is new for users ==

===Write to Journal anytime===
[[File:0.96 Description.png|640px]]

[[File:0.96 Description journal.png|640px]]

This Feature has a long history and many thinking has been going into this for a few cycles. You can now edit the description of your current activity session from within the activity. The main goal is to be able to take notes within the activity context while the activity is still running. To take notes you can reveal the description palette from a button in the activity subtoolbar, it is the same description field that is used in the Journal detail section. You can edit the description in both places, as well from within the detail view while the activity is still running, the description will be updated accordingly.

The naming alert that prompted the learner for taking notes about the activity session when closing the activity has been removed.

Thanks to everyone involved in this great feature, the design team and especially to Walter Bender for his constant effort over several release cycles to make this happen.

===Global Text to Speech===
[[File:0.96 Text-to-speech.png|640px]]

The global text to speech feature gives the learner the ability to let Sugar speak out any selected text in the user interface. It can be accessed by the speech frame device which has the start/pause and stop controls. There are options in this palette to adjust the pitch and rate as well which are restored over boots. For power users the "alt+shift+s" shortcut has been added to control the speak-back.

Thanks to Gonzalo Odiard for bringing this great Feature to us.

===Browse===
[[File:0.96 Browse inline pdf.png|640px]]

Manuel Quiñones did a lot of work on making inline pdf viewing in Browse possible using the Evince backend. If the learner clicks on a pdf file it will open inside the Browse activity in a new tab. At the bottom of the page there are controls to navigate in the pdf, to change the view and to save the pdf to the Journal.

===Read===
''in progress...''

===TurtleArt===
[[File:TurtleArt139.png|640px]]

Turtle Art advanced from Version 116 to Version 139 over the past release cycle. Along with many minor bug fixes:
* Cairo conversion, enabling much improved graphics (anti-aliasing, rotating images and text) and an eventual port to GTK-3
* Overhaul of the plugin mechanism and new plugins for Physics, Nutrition, Butia, WeDo, NXT, et al.
* Overhaul of the help mechanism to make help more readily available
* New blocks for speak, mouse, and audio
* Improved touch support
Many thanks especially to the Butia team that has done stress-testing of the plug-in mechanism and as a result led to many improvements.

===Measure===
[[File:Measure-37.png|640px]]

Measure underwent a major refactoring to enable stereo capture of analog audio and digital data.

===Etoys===
[[File:Etoys5-Home.png|640px|border]]

This Sugar release includes Etoys 5.0, which has many new features, including:

* a “single-step” feature in the scriptor
* a scriptable calendar
* a scriptable “sector” object, allowing you to create slices of a pie of any angle
* a “key press” object, which reports whether, and for how long, a specific key is pressed
* “attached” watchers, which always appear near the object they watch
* number lines, and a “graph paper” tool to make graph-paper-like backgrounds
* new languages: Armenian, Dansk, Papiamentu, Polish

See [http://squeakland.org/download/releaseNotes.jsp#features Etoys Release Notes] for further details.

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.96 developer platform:

=== Activity Authors guidelines ===
The most important change is that the GTK+ 2 based sugar-toolkit has been deprecated. Newly written activities should use sugar-toolkit-gtk3, which is based on GTK+ 3 and Pygobject3, now. There will be only bug fixes being available in the future for the old toolkit no new features will be made available for it and it will probably go away at one point completely. Detailed guidelines for porting existing activities can be found at [[Features/GTK3/Porting]].

=== Widgets ===
The Keep button has been removed completely from the API later; please adjust existing activities accordingly.

=== API ===
In sugar-toolkit-gtk3 API that has been deprecated for several development cycles have been removed:

* Remove support for the old deprecated toolbar
** removed deprecated imports from the activity module, use the widgets module instead
** removed the ActivityToolbox class
** removed the Stop button from the ActivityToolbar
** removed set_toolbar/get_toolbar API from the window module
*Datastore: remove deprecated API
*ObjectChooser: remove deprecated parameters
** The objectchooser had the 'title', 'flags' and 'buttons' parameters deprecated for a long time, remove them now completely. The only parameters allowed are now the 'parent' and the 'what_filter'.
* Bundlebuilder: remove deprecated bundle_name argument
* Activity: remove deprecated _shared_activity member
* ActivityBundle: clean from deprecated code
** removed deprecated mime type 'application/vnd.olpc-x-sugar'
** activity.info file: removed deprecated field 'service_name' use 'bundle_id' instead
** activity.info file: removed deprecated field 'class' use 'exec' instead

== What's new for packagers ==
* the sugar-toolkit-gtk3 repository has been added
* the Browse activity depend webkitgtk3 instead of xulrunner and hulahop, the hulahop module has been deprecated
* etoys 5.0 needs a new Squeak VM plugin for camera access. The [http://lists.squeak.org/pipermail/vm-dev/2012-May/010646.html source] has been submitted to the vm developers but is not in the [http://squeakvm.org/unix/ latest release] (4.4.7) yet

== Internationalization (i18n) and Localization (l10n) ==
[[File:0.96 arabic sugar.png|640px|Sugar localized in Kinyarwanda]]

[[File:0.96 Kinyarwanda.png|640px|Sugar localized in Arabic]]

For the Sucrose 0.96 release, 16 languages are 100% complete (with respect to the core Glucose module).

Armenian, Chinese (China), Chinese (Taiwan), Danish, Dutch, English (United Kingdom), English (US), French, German, Huastec (Tének), Nepali, Polish, Portuguese, Sinhala, Spanish, Thai.

An additional 8 languages are greater than 80% complete.

Arabic, Bengali, Greek, Hindi, Japanese, Kinyarwanda, Tamil, Vietnamese.

With some localization done on a total of 86 languages.

== Compatibility ==
Activities that has been ported to sugar-toolkit-gtk3 will not run on older Sugar versions where the new toolkit is not available. Which means latest Browse and Read will not run on Sugar versions < 0.96. This is reflected in the activity providing backend ASLO where the activities are marked 0.96 only.

== Getting the sources ==
If you want to package Sugar for your favorite distribution or just want to examine Sugar's lovely code here are the released bundles. If you are interested in the full changelog you can use the [http://git.sugarlabs.org/ Sugar git repositories].

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.96.1.tar.bz2 sugar 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.96.0.tar.bz2 sugar-datastore 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.96.1.tar.bz2 sugar-toolkit 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit-gtk3/sugar-toolkit-gtk3-0.96.1.tar.bz2 sugar-toolkit-gtk3 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.96.0.tar.bz2 sugar-base 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.96.2.tar.bz2 sugar-artwork 0.96.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-5.0.2403.tar.gz etoys 5.0.2403]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-46.tar.bz2 Pippy 46]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-137.tar.bz2 Browse 137]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-40.tar.bz2 Calculate 40]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-76.tar.bz2 Chat 76]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-139.tar.bz2 TurtleArt 139]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-23.tar.bz2 Jukebox 23]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-28.tar.bz2 Log 28]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-20.tar.bz2 ImageViewer 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-79.tar.bz2 Write 79]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Terminal/Terminal-36.tar.bz2 Terminal 36]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Read/Read-99.tar.bz2 Read 99]

== How to contribute with testing ==
Sugar 0.96 has been released. We are still stabilizing the areas that have seen major changes like the new stugar-toolkit-gtk3 the new GTK+ 3 Sugar theme and the Browse activity that has been ported to use Webkit. It is very important to get feedback from and that you report the bugs you find. The order of stability depends among other things as well on '''you'''.

If you find bugs please report them into the [http://bugs.sugarlabs.org/ Sugar Labs bug tracker] indicating the 0.96.x version in the ticket version field. If you have hardware from OLPC you can use the [http://build.laptop.org/12.1.0/ 12.1.0 builds] for the i686 architecture (XO 1 and XO 1.5) and the ARM architecture (XO 1.75). Those builds include the latest Sugar 0.96.x. Hardware specific bugs especially with the new 1.75 hardware please report at the [http://dev.laptop.org/ OLPC bug tracker]. The current development version is as well available in [http://fedoraproject.org/wiki/Releases/17 Fedora 17] and [[Development_Team/Jhbuild |sugar-jhbuild]] (sugar* master branches).

==Credits==
This cycle we want to espacially thank the contributors to the GTK+ 3/pygobject3 port of the toolkit! All the attendees of the [[Marketing_Team/Events/Gtk3_Hackfest_2011]] in Praha and the Rosario meetup our warmest "thank you". Kudos go to the Palette people!

Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes and do review other's patches,

* the ''maintainers'' that make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing a Sugar version to test with during the development cycle,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

== Looking forward to 0.98==
In the 0.98 development cycle the porting of the Shell to GTK+ 3 and pygobject3 is a major task. Furthermore the remaining bugs in the new sugar-toolkit-gtk3 should be fixed. We encourage activity developers to port their activity to the new toolkit and GTK+ 3 and pygobject3.

0.96/Notes

2012-05-22T10:37:31Z

Bert: /* Etoys */ Added screenshots

<noinclude>{{ Translations | [[0.94/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]

''Please do not edit unless you are part of the Sugar Release Team. Comments are welcome on the [[{{TALKPAGENAME}}|Discussion page]].''

Sucrose 0.96 Release Notes

== Introduction ==
Sugar 0.96 is the new version of the [http://www.sugarlabs.org/ Sugar learning platform]. It was released the 30th of April 2012 (see [[0.96/Roadmap#Schedule]] for details).

The main changes in this cycle was the introduction of the new sugar-toolkit-gtk3 which is the sugar-toolkit ported to use GTK+ 3 and Pygobject3. Currently Browse, Read, the HellowWorld activity and Abacus have been ported to the new toolkit.

[[File:0.96 Read.png|640px]]

The Read activity has been ported to use the new toolkit.

[[File:0.96 browse.png|640px]]

Besides moving to the new toolkit Browse and related components have been switching to WebKit as its back-end technology.

== What is new for users ==

===Write to Journal anytime===
[[File:0.96 Description.png|640px]]

[[File:0.96 Description journal.png|640px]]

This Feature has a long history and many thinking has been going into this for a few cycles. You can now edit the description of your current activity session from within the activity. The main goal is to be able to take notes within the activity context while the activity is still running. To take notes you can reveal the description palette from a button in the activity subtoolbar, it is the same description field that is used in the Journal detail section. You can edit the description in both places, as well from within the detail view while the activity is still running, the description will be updated accordingly.

The naming alert that prompted the learner for taking notes about the activity session when closing the activity has been removed.

Thanks to everyone involved in this great feature, the design team and especially to Walter Bender for his constant effort over several release cycles to make this happen.

===Global Text to Speech===
[[File:0.96 Text-to-speech.png|640px]]

The global text to speech feature gives the learner the ability to let Sugar speak out any selected text in the user interface. It can be accessed by the speech frame device which has the start/pause and stop controls. There are options in this palette to adjust the pitch and rate as well which are restored over boots. For power users the "alt+shift+s" shortcut has been added to control the speak-back.

Thanks to Gonzalo Odiard for bringing this great Feature to us.

===Browse===
[[File:0.96 Browse inline pdf.png|640px]]

Manuel Quiñones did a lot of work on making inline pdf viewing in Browse possible using the Evince backend. If the learner clicks on a pdf file it will open inside the Browse activity in a new tab. At the bottom of the page there are controls to navigate in the pdf, to change the view and to save the pdf to the Journal.

===Read===
''in progress...''

===TurtleArt===
[[File:TurtleArt139.png|640px]]

Turtle Art advanced from Version 116 to Version 139 over the past release cycle. Along with many minor bug fixes:
* Cairo conversion, enabling much improved graphics (anti-aliasing, rotating images and text) and an eventual port to GTK-3
* Overhaul of the plugin mechanism and new plugins for Physics, Nutrition, Butia, WeDo, NXT, et al.
* Overhaul of the help mechanism to make help more readily available
* New blocks for speak, mouse, and audio
* Improved touch support
Many thanks especially to the Butia team that has done stress-testing of the plug-in mechanism and as a result led to many improvements.

===Measure===
[[File:Measure-37.png|640px]]

Measure underwent a major refactoring to enable stereo capture of analog audio and digital data.

===Etoys===
[[File:Etoys5-Home.png|640px|border]]

This Sugar release includes Etoys 5.0, which has many new features, including:

* a “single-step” feature in the scriptor
* a scriptable calendar
* a scriptable “sector” object, allowing you to create slices of a pie of any angle
* a “key press” object, which reports whether, and for how long, a specific key is pressed
* “attached” watchers, which always appear near the object they watch
* number lines, and a “graph paper” tool to make graph-paper-like backgrounds
* new languages: Armenian, Dansk, Papiamentu, Polish

See [http://squeakland.org/download/releaseNotes.jsp Etoys Release Notes] for further details.

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.96 developer platform:

=== Activity Authors guidelines ===
The most important change is that the GTK+ 2 based sugar-toolkit has been deprecated. Newly written activities should use sugar-toolkit-gtk3, which is based on GTK+ 3 and Pygobject3, now. There will be only bug fixes being available in the future for the old toolkit no new features will be made available for it and it will probably go away at one point completely. Detailed guidelines for porting existing activities can be found at [[Features/GTK3/Porting]].

=== Widgets ===
The Keep button has been removed completely from the API later; please adjust existing activities accordingly.

=== API ===
In sugar-toolkit-gtk3 API that has been deprecated for several development cycles have been removed:

* Remove support for the old deprecated toolbar
** removed deprecated imports from the activity module, use the widgets module instead
** removed the ActivityToolbox class
** removed the Stop button from the ActivityToolbar
** removed set_toolbar/get_toolbar API from the window module
*Datastore: remove deprecated API
*ObjectChooser: remove deprecated parameters
** The objectchooser had the 'title', 'flags' and 'buttons' parameters deprecated for a long time, remove them now completely. The only parameters allowed are now the 'parent' and the 'what_filter'.
* Bundlebuilder: remove deprecated bundle_name argument
* Activity: remove deprecated _shared_activity member
* ActivityBundle: clean from deprecated code
** removed deprecated mime type 'application/vnd.olpc-x-sugar'
** activity.info file: removed deprecated field 'service_name' use 'bundle_id' instead
** activity.info file: removed deprecated field 'class' use 'exec' instead

== What's new for packagers ==
* the sugar-toolkit-gtk3 repository has been added
* the Browse activity depend webkitgtk3 instead of xulrunner and hulahop, the hulahop module has been deprecated
* etoys 5.0 needs a new Squeak VM plugin for camera access. The [http://lists.squeak.org/pipermail/vm-dev/2012-May/010646.html source] has been submitted to the vm developers but is not in the [http://squeakvm.org/unix/ latest release] (4.4.7) yet

== Internationalization (i18n) and Localization (l10n) ==
[[File:0.96 arabic sugar.png|640px|Sugar localized in Kinyarwanda]]

[[File:0.96 Kinyarwanda.png|640px|Sugar localized in Arabic]]

For the Sucrose 0.96 release, 16 languages are 100% complete (with respect to the core Glucose module).

Armenian, Chinese (China), Chinese (Taiwan), Danish, Dutch, English (United Kingdom), English (US), French, German, Huastec (Tének), Nepali, Polish, Portuguese, Sinhala, Spanish, Thai.

An additional 8 languages are greater than 80% complete.

Arabic, Bengali, Greek, Hindi, Japanese, Kinyarwanda, Tamil, Vietnamese.

With some localization done on a total of 86 languages.

== Compatibility ==
Activities that has been ported to sugar-toolkit-gtk3 will not run on older Sugar versions where the new toolkit is not available. Which means latest Browse and Read will not run on Sugar versions < 0.96. This is reflected in the activity providing backend ASLO where the activities are marked 0.96 only.

== Getting the sources ==
If you want to package Sugar for your favorite distribution or just want to examine Sugar's lovely code here are the released bundles. If you are interested in the full changelog you can use the [http://git.sugarlabs.org/ Sugar git repositories].

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.96.1.tar.bz2 sugar 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.96.0.tar.bz2 sugar-datastore 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.96.1.tar.bz2 sugar-toolkit 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit-gtk3/sugar-toolkit-gtk3-0.96.1.tar.bz2 sugar-toolkit-gtk3 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.96.0.tar.bz2 sugar-base 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.96.2.tar.bz2 sugar-artwork 0.96.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-5.0.2403.tar.gz etoys 5.0.2403]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-46.tar.bz2 Pippy 46]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-137.tar.bz2 Browse 137]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-40.tar.bz2 Calculate 40]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-76.tar.bz2 Chat 76]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-139.tar.bz2 TurtleArt 139]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-23.tar.bz2 Jukebox 23]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-28.tar.bz2 Log 28]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-20.tar.bz2 ImageViewer 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-79.tar.bz2 Write 79]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Terminal/Terminal-36.tar.bz2 Terminal 36]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Read/Read-99.tar.bz2 Read 99]

== How to contribute with testing ==
Sugar 0.96 has been released. We are still stabilizing the areas that have seen major changes like the new stugar-toolkit-gtk3 the new GTK+ 3 Sugar theme and the Browse activity that has been ported to use Webkit. It is very important to get feedback from and that you report the bugs you find. The order of stability depends among other things as well on '''you'''.

If you find bugs please report them into the [http://bugs.sugarlabs.org/ Sugar Labs bug tracker] indicating the 0.96.x version in the ticket version field. If you have hardware from OLPC you can use the [http://build.laptop.org/12.1.0/ 12.1.0 builds] for the i686 architecture (XO 1 and XO 1.5) and the ARM architecture (XO 1.75). Those builds include the latest Sugar 0.96.x. Hardware specific bugs especially with the new 1.75 hardware please report at the [http://dev.laptop.org/ OLPC bug tracker]. The current development version is as well available in [http://fedoraproject.org/wiki/Releases/17 Fedora 17] and [[Development_Team/Jhbuild |sugar-jhbuild]] (sugar* master branches).

==Credits==
This cycle we want to espacially thank the contributors to the GTK+ 3/pygobject3 port of the toolkit! All the attendees of the [[Marketing_Team/Events/Gtk3_Hackfest_2011]] in Praha and the Rosario meetup our warmest "thank you". Kudos go to the Palette people!

Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes and do review other's patches,

* the ''maintainers'' that make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing a Sugar version to test with during the development cycle,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

== Looking forward to 0.98==
In the 0.98 development cycle the porting of the Shell to GTK+ 3 and pygobject3 is a major task. Furthermore the remaining bugs in the new sugar-toolkit-gtk3 should be fixed. We encourage activity developers to port their activity to the new toolkit and GTK+ 3 and pygobject3.

File:Etoys5-Home.png

2012-05-22T10:34:09Z

Bert: Screenshot of Etoys 5 with pen tracing enabled for little red car

Screenshot of Etoys 5 with pen tracing enabled for little red car

0.96/Notes

2012-05-22T10:17:10Z

Bert: /* What's new for packagers */ need new Squeak VM

<noinclude>{{ Translations | [[0.94/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]

''Please do not edit unless you are part of the Sugar Release Team. Comments are welcome on the [[{{TALKPAGENAME}}|Discussion page]].''

Sucrose 0.96 Release Notes

== Introduction ==
Sugar 0.96 is the new version of the [http://www.sugarlabs.org/ Sugar learning platform]. It was released the 30th of April 2012 (see [[0.96/Roadmap#Schedule]] for details).

The main changes in this cycle was the introduction of the new sugar-toolkit-gtk3 which is the sugar-toolkit ported to use GTK+ 3 and Pygobject3. Currently Browse, Read, the HellowWorld activity and Abacus have been ported to the new toolkit.

[[File:0.96 Read.png|640px]]

The Read activity has been ported to use the new toolkit.

[[File:0.96 browse.png|640px]]

Besides moving to the new toolkit Browse and related components have been switching to WebKit as its back-end technology.

== What is new for users ==

===Write to Journal anytime===
[[File:0.96 Description.png|640px]]

[[File:0.96 Description journal.png|640px]]

This Feature has a long history and many thinking has been going into this for a few cycles. You can now edit the description of your current activity session from within the activity. The main goal is to be able to take notes within the activity context while the activity is still running. To take notes you can reveal the description palette from a button in the activity subtoolbar, it is the same description field that is used in the Journal detail section. You can edit the description in both places, as well from within the detail view while the activity is still running, the description will be updated accordingly.

The naming alert that prompted the learner for taking notes about the activity session when closing the activity has been removed.

Thanks to everyone involved in this great feature, the design team and especially to Walter Bender for his constant effort over several release cycles to make this happen.

===Global Text to Speech===
[[File:0.96 Text-to-speech.png|640px]]

The global text to speech feature gives the learner the ability to let Sugar speak out any selected text in the user interface. It can be accessed by the speech frame device which has the start/pause and stop controls. There are options in this palette to adjust the pitch and rate as well which are restored over boots. For power users the "alt+shift+s" shortcut has been added to control the speak-back.

Thanks to Gonzalo Odiard for bringing this great Feature to us.

===Browse===
[[File:0.96 Browse inline pdf.png|640px]]

Manuel Quiñones did a lot of work on making inline pdf viewing in Browse possible using the Evince backend. If the learner clicks on a pdf file it will open inside the Browse activity in a new tab. At the bottom of the page there are controls to navigate in the pdf, to change the view and to save the pdf to the Journal.

===Read===
''in progress...''

===TurtleArt===
[[File:TurtleArt139.png|640px]]

Turtle Art advanced from Version 116 to Version 139 over the past release cycle. Along with many minor bug fixes:
* Cairo conversion, enabling much improved graphics (anti-aliasing, rotating images and text) and an eventual port to GTK-3
* Overhaul of the plugin mechanism and new plugins for Physics, Nutrition, Butia, WeDo, NXT, et al.
* Overhaul of the help mechanism to make help more readily available
* New blocks for speak, mouse, and audio
* Improved touch support
Many thanks especially to the Butia team that has done stress-testing of the plug-in mechanism and as a result led to many improvements.

===Measure===
[[File:Measure-37.png|640px]]

Measure underwent a major refactoring to enable stereo capture of analog audio and digital data.

===Etoys===
This Sugar release includes Etoys 5.0, which has many new features, including:

* a “single-step” feature in the scriptor
* a scriptable calendar
* a scriptable “sector” object, allowing you to create slices of a pie of any angle
* a “key press” object, which reports whether, and for how long, a specific key is pressed
* “attached” watchers, which always appear near the object they watch
* number lines, and a “graph paper” tool to make graph-paper-like backgrounds
* new languages: Armenian, Dansk, Papiamentu, Polish

See [http://squeakland.org/download/releaseNotes.jsp Etoys Release Notes] for further details.

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.96 developer platform:

=== Activity Authors guidelines ===
The most important change is that the GTK+ 2 based sugar-toolkit has been deprecated. Newly written activities should use sugar-toolkit-gtk3, which is based on GTK+ 3 and Pygobject3, now. There will be only bug fixes being available in the future for the old toolkit no new features will be made available for it and it will probably go away at one point completely. Detailed guidelines for porting existing activities can be found at [[Features/GTK3/Porting]].

=== Widgets ===
The Keep button has been removed completely from the API later; please adjust existing activities accordingly.

=== API ===
In sugar-toolkit-gtk3 API that has been deprecated for several development cycles have been removed:

* Remove support for the old deprecated toolbar
** removed deprecated imports from the activity module, use the widgets module instead
** removed the ActivityToolbox class
** removed the Stop button from the ActivityToolbar
** removed set_toolbar/get_toolbar API from the window module
*Datastore: remove deprecated API
*ObjectChooser: remove deprecated parameters
** The objectchooser had the 'title', 'flags' and 'buttons' parameters deprecated for a long time, remove them now completely. The only parameters allowed are now the 'parent' and the 'what_filter'.
* Bundlebuilder: remove deprecated bundle_name argument
* Activity: remove deprecated _shared_activity member
* ActivityBundle: clean from deprecated code
** removed deprecated mime type 'application/vnd.olpc-x-sugar'
** activity.info file: removed deprecated field 'service_name' use 'bundle_id' instead
** activity.info file: removed deprecated field 'class' use 'exec' instead

== What's new for packagers ==
* the sugar-toolkit-gtk3 repository has been added
* the Browse activity depend webkitgtk3 instead of xulrunner and hulahop, the hulahop module has been deprecated
* etoys 5.0 needs a new Squeak VM plugin for camera access. The [http://lists.squeak.org/pipermail/vm-dev/2012-May/010646.html source] has been submitted to the vm developers but is not in the [http://squeakvm.org/unix/ latest release] (4.4.7) yet

== Internationalization (i18n) and Localization (l10n) ==
[[File:0.96 arabic sugar.png|640px|Sugar localized in Kinyarwanda]]

[[File:0.96 Kinyarwanda.png|640px|Sugar localized in Arabic]]

For the Sucrose 0.96 release, 16 languages are 100% complete (with respect to the core Glucose module).

Armenian, Chinese (China), Chinese (Taiwan), Danish, Dutch, English (United Kingdom), English (US), French, German, Huastec (Tének), Nepali, Polish, Portuguese, Sinhala, Spanish, Thai.

An additional 8 languages are greater than 80% complete.

Arabic, Bengali, Greek, Hindi, Japanese, Kinyarwanda, Tamil, Vietnamese.

With some localization done on a total of 86 languages.

== Compatibility ==
Activities that has been ported to sugar-toolkit-gtk3 will not run on older Sugar versions where the new toolkit is not available. Which means latest Browse and Read will not run on Sugar versions < 0.96. This is reflected in the activity providing backend ASLO where the activities are marked 0.96 only.

== Getting the sources ==
If you want to package Sugar for your favorite distribution or just want to examine Sugar's lovely code here are the released bundles. If you are interested in the full changelog you can use the [http://git.sugarlabs.org/ Sugar git repositories].

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.96.1.tar.bz2 sugar 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.96.0.tar.bz2 sugar-datastore 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.96.1.tar.bz2 sugar-toolkit 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit-gtk3/sugar-toolkit-gtk3-0.96.1.tar.bz2 sugar-toolkit-gtk3 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.96.0.tar.bz2 sugar-base 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.96.2.tar.bz2 sugar-artwork 0.96.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-5.0.2403.tar.gz etoys 5.0.2403]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-46.tar.bz2 Pippy 46]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-137.tar.bz2 Browse 137]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-40.tar.bz2 Calculate 40]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-76.tar.bz2 Chat 76]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-139.tar.bz2 TurtleArt 139]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-23.tar.bz2 Jukebox 23]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-28.tar.bz2 Log 28]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-20.tar.bz2 ImageViewer 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-79.tar.bz2 Write 79]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Terminal/Terminal-36.tar.bz2 Terminal 36]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Read/Read-99.tar.bz2 Read 99]

== How to contribute with testing ==
Sugar 0.96 has been released. We are still stabilizing the areas that have seen major changes like the new stugar-toolkit-gtk3 the new GTK+ 3 Sugar theme and the Browse activity that has been ported to use Webkit. It is very important to get feedback from and that you report the bugs you find. The order of stability depends among other things as well on '''you'''.

If you find bugs please report them into the [http://bugs.sugarlabs.org/ Sugar Labs bug tracker] indicating the 0.96.x version in the ticket version field. If you have hardware from OLPC you can use the [http://build.laptop.org/12.1.0/ 12.1.0 builds] for the i686 architecture (XO 1 and XO 1.5) and the ARM architecture (XO 1.75). Those builds include the latest Sugar 0.96.x. Hardware specific bugs especially with the new 1.75 hardware please report at the [http://dev.laptop.org/ OLPC bug tracker]. The current development version is as well available in [http://fedoraproject.org/wiki/Releases/17 Fedora 17] and [[Development_Team/Jhbuild |sugar-jhbuild]] (sugar* master branches).

==Credits==
This cycle we want to espacially thank the contributors to the GTK+ 3/pygobject3 port of the toolkit! All the attendees of the [[Marketing_Team/Events/Gtk3_Hackfest_2011]] in Praha and the Rosario meetup our warmest "thank you". Kudos go to the Palette people!

Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes and do review other's patches,

* the ''maintainers'' that make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing a Sugar version to test with during the development cycle,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

== Looking forward to 0.98==
In the 0.98 development cycle the porting of the Shell to GTK+ 3 and pygobject3 is a major task. Furthermore the remaining bugs in the new sugar-toolkit-gtk3 should be fixed. We encourage activity developers to port their activity to the new toolkit and GTK+ 3 and pygobject3.

0.96/Notes

2012-05-22T10:11:50Z

Bert: /* Etoys */ Added

<noinclude>{{ Translations | [[0.94/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]

''Please do not edit unless you are part of the Sugar Release Team. Comments are welcome on the [[{{TALKPAGENAME}}|Discussion page]].''

Sucrose 0.96 Release Notes

== Introduction ==
Sugar 0.96 is the new version of the [http://www.sugarlabs.org/ Sugar learning platform]. It was released the 30th of April 2012 (see [[0.96/Roadmap#Schedule]] for details).

The main changes in this cycle was the introduction of the new sugar-toolkit-gtk3 which is the sugar-toolkit ported to use GTK+ 3 and Pygobject3. Currently Browse, Read, the HellowWorld activity and Abacus have been ported to the new toolkit.

[[File:0.96 Read.png|640px]]

The Read activity has been ported to use the new toolkit.

[[File:0.96 browse.png|640px]]

Besides moving to the new toolkit Browse and related components have been switching to WebKit as its back-end technology.

== What is new for users ==

===Write to Journal anytime===
[[File:0.96 Description.png|640px]]

[[File:0.96 Description journal.png|640px]]

This Feature has a long history and many thinking has been going into this for a few cycles. You can now edit the description of your current activity session from within the activity. The main goal is to be able to take notes within the activity context while the activity is still running. To take notes you can reveal the description palette from a button in the activity subtoolbar, it is the same description field that is used in the Journal detail section. You can edit the description in both places, as well from within the detail view while the activity is still running, the description will be updated accordingly.

The naming alert that prompted the learner for taking notes about the activity session when closing the activity has been removed.

Thanks to everyone involved in this great feature, the design team and especially to Walter Bender for his constant effort over several release cycles to make this happen.

===Global Text to Speech===
[[File:0.96 Text-to-speech.png|640px]]

The global text to speech feature gives the learner the ability to let Sugar speak out any selected text in the user interface. It can be accessed by the speech frame device which has the start/pause and stop controls. There are options in this palette to adjust the pitch and rate as well which are restored over boots. For power users the "alt+shift+s" shortcut has been added to control the speak-back.

Thanks to Gonzalo Odiard for bringing this great Feature to us.

===Browse===
[[File:0.96 Browse inline pdf.png|640px]]

Manuel Quiñones did a lot of work on making inline pdf viewing in Browse possible using the Evince backend. If the learner clicks on a pdf file it will open inside the Browse activity in a new tab. At the bottom of the page there are controls to navigate in the pdf, to change the view and to save the pdf to the Journal.

===Read===
''in progress...''

===TurtleArt===
[[File:TurtleArt139.png|640px]]

Turtle Art advanced from Version 116 to Version 139 over the past release cycle. Along with many minor bug fixes:
* Cairo conversion, enabling much improved graphics (anti-aliasing, rotating images and text) and an eventual port to GTK-3
* Overhaul of the plugin mechanism and new plugins for Physics, Nutrition, Butia, WeDo, NXT, et al.
* Overhaul of the help mechanism to make help more readily available
* New blocks for speak, mouse, and audio
* Improved touch support
Many thanks especially to the Butia team that has done stress-testing of the plug-in mechanism and as a result led to many improvements.

===Measure===
[[File:Measure-37.png|640px]]

Measure underwent a major refactoring to enable stereo capture of analog audio and digital data.

===Etoys===
This Sugar release includes Etoys 5.0, which has many new features, including:

* a “single-step” feature in the scriptor
* a scriptable calendar
* a scriptable “sector” object, allowing you to create slices of a pie of any angle
* a “key press” object, which reports whether, and for how long, a specific key is pressed
* “attached” watchers, which always appear near the object they watch
* number lines, and a “graph paper” tool to make graph-paper-like backgrounds
* new languages: Armenian, Dansk, Papiamentu, Polish

See [http://squeakland.org/download/releaseNotes.jsp Etoys Release Notes] for further details.

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.96 developer platform:

=== Activity Authors guidelines ===
The most important change is that the GTK+ 2 based sugar-toolkit has been deprecated. Newly written activities should use sugar-toolkit-gtk3, which is based on GTK+ 3 and Pygobject3, now. There will be only bug fixes being available in the future for the old toolkit no new features will be made available for it and it will probably go away at one point completely. Detailed guidelines for porting existing activities can be found at [[Features/GTK3/Porting]].

=== Widgets ===
The Keep button has been removed completely from the API later; please adjust existing activities accordingly.

=== API ===
In sugar-toolkit-gtk3 API that has been deprecated for several development cycles have been removed:

* Remove support for the old deprecated toolbar
** removed deprecated imports from the activity module, use the widgets module instead
** removed the ActivityToolbox class
** removed the Stop button from the ActivityToolbar
** removed set_toolbar/get_toolbar API from the window module
*Datastore: remove deprecated API
*ObjectChooser: remove deprecated parameters
** The objectchooser had the 'title', 'flags' and 'buttons' parameters deprecated for a long time, remove them now completely. The only parameters allowed are now the 'parent' and the 'what_filter'.
* Bundlebuilder: remove deprecated bundle_name argument
* Activity: remove deprecated _shared_activity member
* ActivityBundle: clean from deprecated code
** removed deprecated mime type 'application/vnd.olpc-x-sugar'
** activity.info file: removed deprecated field 'service_name' use 'bundle_id' instead
** activity.info file: removed deprecated field 'class' use 'exec' instead

== What's new for packagers ==
* the sugar-toolkit-gtk3 repository has been added
* the Browse activity depend webkitgtk3 instead of xulrunner and hulahop, the hulahop module has been deprecated

== Internationalization (i18n) and Localization (l10n) ==
[[File:0.96 arabic sugar.png|640px|Sugar localized in Kinyarwanda]]

[[File:0.96 Kinyarwanda.png|640px|Sugar localized in Arabic]]

For the Sucrose 0.96 release, 16 languages are 100% complete (with respect to the core Glucose module).

Armenian, Chinese (China), Chinese (Taiwan), Danish, Dutch, English (United Kingdom), English (US), French, German, Huastec (Tének), Nepali, Polish, Portuguese, Sinhala, Spanish, Thai.

An additional 8 languages are greater than 80% complete.

Arabic, Bengali, Greek, Hindi, Japanese, Kinyarwanda, Tamil, Vietnamese.

With some localization done on a total of 86 languages.

== Compatibility ==
Activities that has been ported to sugar-toolkit-gtk3 will not run on older Sugar versions where the new toolkit is not available. Which means latest Browse and Read will not run on Sugar versions < 0.96. This is reflected in the activity providing backend ASLO where the activities are marked 0.96 only.

== Getting the sources ==
If you want to package Sugar for your favorite distribution or just want to examine Sugar's lovely code here are the released bundles. If you are interested in the full changelog you can use the [http://git.sugarlabs.org/ Sugar git repositories].

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.96.1.tar.bz2 sugar 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.96.0.tar.bz2 sugar-datastore 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.96.1.tar.bz2 sugar-toolkit 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit-gtk3/sugar-toolkit-gtk3-0.96.1.tar.bz2 sugar-toolkit-gtk3 0.96.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.96.0.tar.bz2 sugar-base 0.96.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.96.2.tar.bz2 sugar-artwork 0.96.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-5.0.2403.tar.gz etoys 5.0.2403]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-46.tar.bz2 Pippy 46]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-137.tar.bz2 Browse 137]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-40.tar.bz2 Calculate 40]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-76.tar.bz2 Chat 76]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-139.tar.bz2 TurtleArt 139]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-23.tar.bz2 Jukebox 23]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-28.tar.bz2 Log 28]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-20.tar.bz2 ImageViewer 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-79.tar.bz2 Write 79]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Terminal/Terminal-36.tar.bz2 Terminal 36]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Read/Read-99.tar.bz2 Read 99]

== How to contribute with testing ==
Sugar 0.96 has been released. We are still stabilizing the areas that have seen major changes like the new stugar-toolkit-gtk3 the new GTK+ 3 Sugar theme and the Browse activity that has been ported to use Webkit. It is very important to get feedback from and that you report the bugs you find. The order of stability depends among other things as well on '''you'''.

If you find bugs please report them into the [http://bugs.sugarlabs.org/ Sugar Labs bug tracker] indicating the 0.96.x version in the ticket version field. If you have hardware from OLPC you can use the [http://build.laptop.org/12.1.0/ 12.1.0 builds] for the i686 architecture (XO 1 and XO 1.5) and the ARM architecture (XO 1.75). Those builds include the latest Sugar 0.96.x. Hardware specific bugs especially with the new 1.75 hardware please report at the [http://dev.laptop.org/ OLPC bug tracker]. The current development version is as well available in [http://fedoraproject.org/wiki/Releases/17 Fedora 17] and [[Development_Team/Jhbuild |sugar-jhbuild]] (sugar* master branches).

==Credits==
This cycle we want to espacially thank the contributors to the GTK+ 3/pygobject3 port of the toolkit! All the attendees of the [[Marketing_Team/Events/Gtk3_Hackfest_2011]] in Praha and the Rosario meetup our warmest "thank you". Kudos go to the Palette people!

Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes and do review other's patches,

* the ''maintainers'' that make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing a Sugar version to test with during the development cycle,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

== Looking forward to 0.98==
In the 0.98 development cycle the porting of the Shell to GTK+ 3 and pygobject3 is a major task. Furthermore the remaining bugs in the new sugar-toolkit-gtk3 should be fixed. We encourage activity developers to port their activity to the new toolkit and GTK+ 3 and pygobject3.

Development Team/Low-level Activity API

2012-03-18T16:20:18Z

Bert: /* Presence */ add link to collaboration section

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. See [[#Collaboration|below]] for details''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-11-01T11:18:56Z

Bert: /* Startup */ mention "unshared" startup

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

If a room is found, the activity needs to join it immediately (see [[#Joining|below]]). Otherwise, a normal "unshared" activity startup should commence.

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-11-01T11:16:22Z

Bert: /* Telepathy */ connection availability

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one. Since connections can become available later, you need to either track changes using D-Bus signals, or do the above every time a new connection is needed.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. If so, it needs to be joined (see [[#Joining|below]]). The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-11-01T11:13:27Z

Bert: /* Collaboration */ clarify multiple connections

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

This gathers all the usable connections, there may be more than one.

== Startup ==

On startup, an activity needs to check all the currently available connections if there is already a "room" for it. If so, it needs to be joined (see [[#Joining|below]]). The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-11-01T11:09:36Z

Bert: /* Telepathy */ link to dev manual

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification] and the [http://telepathy.freedesktop.org/doc/book/ Telepathy Manual]. The code below is pseudo code, you need to adapt it for your specific programming language.

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

There may be more than one valid connection.

== Startup ==

On startup, an activity needs to check if there is already a "room" for it. If so, it needs to be joined (see [[#Joining|below]]). The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Telepathy

2011-11-01T11:03:57Z

Bert: Link to telepathy.freedesktop.org

Extensive documentation can be found at [http://telepathy.freedesktop.org/ telepathy.freedesktop.org].

There is some older (possibly outdated) documentation on the [[olpc:Telepathy|OLPC wiki]]

[[Category:Python modules]]

Development Team/Low-level Activity API

2011-10-31T23:48:42Z

Bert: /* Collaboration */ AccountManager

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Telepathy ==

For details, please refer to the [http://telepathy.freedesktop.org/spec/ Telepathy Specification].

The entry point to Telepathy is the AccountManager:

Service: org.freedesktop.Telepathy.AccountManager
Interface: org.freedesktop.Telepathy.AccountManager
Object Path: /org/freedesktop/Telepathy/AccountManager

It has a list of valid Accounts. Each account has a Connection property, which is valid if its D-Bus path is not '/', and connected if the account's ConnectionStatus property is 0 (1 means connecting, 2 disconnected).

accounts = accountManager.Get('ValidAccounts')
for account in accounts:
connection = account.Get('Connection')
if connection.path != '/' && account.Get('ConnectionStatus') == 0:
connections.add(connection)

There may be more than one valid connection.

== Startup ==

On startup, an activity needs to check if there is already a "room" for it. If so, it needs to be joined (see [[#Joining|below]]). The GetActivity method checks for the room given an activity_id:

for connection in connections:
room_handle = connection.GetActivity(activityId) # may fail

It is provided by the non-standard ActivityProperties interface:

INTERFACE org.laptop.Telepathy.ActivityProperties
METHOD GetActivity(activity_id:s) => (room:u)
METHOD GetProperties(room:u) => (properties:a{sv})
METHOD SetProperties(room:u, properties:a{sv}) => ()
SIGNAL ActivityPropertiesChanged(room:u, properties:a{sv})

== Joining ==

If the activity finds itself to be shared already on startup, or the user chooses to enable sharing later, it needs to "join" the room used for communication:

* create text channel
* create tubes channel
* add self to group

''to be documented''

== Leaving ==

''to be documented''

== Inviting ==

''to be documented''

== Communicating ==

This depends on the needs of the activity, but in general it would

* create a tube in tubes channel
* use the tube for communication

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-10-31T19:46:58Z

Bert: /* Collaboration */ Start documenting Telepathy API

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

= Collaboration =

Sharing and collaboration are core principles in Sugar. They are implemented using [[Telepathy]].

'''Note:''' ''The [[#Presence|Presence Service]] (which was a wrapper around Telepathy in earlier Sugar releases) has been deprecated. Activities need to use Telepathy directly.''

== Sharing ==

''to be documented''

== Inviting ==

''to be documented''

== Joining ==

''to be documented''

== Leaving ==

''to be documented''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-10-31T19:15:33Z

Bert: /* Presence */ Presence Service has been deprecated. Use Telepathy instead.

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

''Note: The Presence Service has been deprecated. Activities need to talk to [[Telepathy]] directly instead. Details on that will be added to this page soonish''

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''to be continued. In the mean time, see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-10-31T19:11:01Z

Bert: /* Activity Life Cycle */ another Presence Service mention

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like Telepathy (the collaboration framework).
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''to be continued. In the mean time, see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

[[Category:API]]
[[Category:Collaboration]]

Development Team/Low-level Activity API

2011-10-31T19:07:46Z

Bert: /* Activity Life Cycle */ remove Presence Service mention

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# It needs to set up collaboration by connecting to the shared activity instance (if any).

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like the Presence Service.
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it needs to create a shared activity instance.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''to be continued. In the mean time, see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

[[Category:API]]
[[Category:Collaboration]]

Marketing Team/Events/Gtk3 Hackfest 2011

2011-10-30T10:20:22Z

Bert: /* Impressions */ added beer photo

{{TOCright}}

= Gtk3 Hackfest 2011 =
Two major changes have recently occurred in Sugar's underlying technologies. Firstly, GTK+ 2 has been obsoleted by GTK+ 3, and GNOME is now based on GTK+ 3. Secondly, PyGTK, the underlying Python library that Sugar uses to call into GTK+, has been deprecated in favour of PyGObject Introspection (hereafter "PyGI"). More background info can be found at [[Features/GTK3]]. Goal of this hackfest is to remove the biggest blockers before we can start the porting and potentially start porting over.

[[File:Brmlab_impressions.jpg|400px]]

== Event Details ==

'''Location:''' Praha (Prague), Czech Republic

The hackfest will be held at the [http://brmlab.cz/| brmlab a hackerspace in Prague]. The place is located [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=Bubensk%C3%A1+1,+Praha-Praha+7,+%C4%8Cesk%C3%A1+republika&sll=37.0625,-95.677068&sspn=65.390746,135.263672&ie=UTF8&hq=&hnear=Bubensk%C3%A1+1477/1,+170+00+Praha+7-Hole%C5%A1ovice,+Czech+Republic&view=map|Map here], using [http://idos.dpp.cz/idos/ConnForm.aspx?tt=pid&cl=E5|Prague public transport] you can get here easily, just hop off at (Metro & Tram stop: "Vltavska").

'''Date:''' Friday, October 28th - Sunday October 30th 2011

'''Primary contact:''' Simon Schampijer <simon AT laptop DOT org>

'''Secondary contact:''' Tomeu Vizoso <tomeu.vizoso AT collabora DOT co DOT uk>

== Target audience ==
Sugar developers

== Sponsors ==
[[File:Brmlab.jpg|300px]] We want to thank [http://brmlab.cz/| brmlab] for hosting us during the week.

[[File:Olpc_logo.png|300px]] We want to thank the [http://laptop.org OLPC Foundation] for sponsoring regional trips to the event.

== Sponsoring regional trips ==
This Hackfest is sponsored by the [http://laptop.org OLPC Foundation]. If you need help for funding your travel, please send an email to simon AT laptop DOT org before 8th of October 2011. We won't be able to refund more than 150 USD per trip, and we will fund regional (european) travels in priority.

== Agenda, goals ==
* Removing Hippo and other custom widgets
** Do we do this before or after GTK3? Note transparent window / icon overlapping issue.
* migration path to Gtk3 (do we ship two toolkits? Do we migrate the shell and the toolkit and activities at once?)
** This is expected to be resolved in advance at [[Features/GTK3]].
* porting Sugar's theme to gtk3 (go benzea, go!)
* Port sugar-toolkit to GTK3 and release sugar-toolkit-0.95.x
* Port Read to GTK3
* Port Browse to Webkit/GTK3
* other introspected libraries that need work (namely NM)

== Measuring your success ==
''coming soon...''

== Attendants ==

Are you planning to attend? Add your name and contact info below!
# [[User:Erikos | Simon Schampijer]]
# [[User:Tomeu | Tomeu Vizoso]]
# [[User:Rgs | Raúl Gutiérrez Segalés]]
# [[User:Walter | Walter Bender]]
# [[User:BenjaminBerg | Benjamin Berg]]
# [[User:DanielDrake | Daniel Drake]]
# [[User:marcopg|Marco Pesenti Gritti]]
# [[User:Cjb|Chris Ball]] (just for Friday, in Prague 22-28 Oct for Kernel Summit/LinuxCon)
# [[User:Ritafreudenberg|Rita Freudenberg]]
# [[User:bert|Bert Freudenberg]]
# [[Martin Schüssler]]

== Accommodation ==
This is a table to find out when people do need accommodation during the hackfest.

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Name !! 27.10.11 !! 28.10.11 !! 29.10.11 !! 30.10.11 !! 31.10.11 !! Note
|-
! Simon Schampijer
| - || yes || yes || yes || - || -
|-
! Raúl Gutiérrez Segalés
| yes || yes || yes || yes || yes || -
|-
! Walter Bender
| yes || yes || yes || yes || yes || -
|-
! Benjamin Berg
| - || yes || yes || yes || - || Arriving 28.10. 10:15; leaving 31.10. 18:31 Uhr
|-
! Daniel Drake
| - || yes || yes || yes || - || travel confirmed: arriving 28th at 10:20, leaving 31st at 06:00
|}

== Lodging ==
This one does seem to be a reasonable offer: http://www.booking.com/hotel/cz/plus-prague-hostel.en-us.html?sid=efb1e369a800d8137da1013763ae00e9;checkin=2011-10-27;checkout=2011-10-30;srfid=8d0e0147ab19098770fd94887bfca1e1X1

== Schedule ==

=== Friday, October 28 ===

=== Saturday, October 29 ===

=== Sunday, October 30 ===

== Impressions ==
''link your photos, add your comments here''

[[File:Hackfest-Prague-2011.jpg]]

[[Category:Event]]

File:Hackfest-Prague-2011.jpg

2011-10-30T10:18:07Z

Bert: Saturday night beer at Tomeu's favorite pub. Great beer. Photo by Bert Freudenberg

Saturday night beer at Tomeu's favorite pub. Great beer. Photo by [[User:bert|Bert Freudenberg]]

Talk:Licensing

2011-06-24T15:11:14Z

Bert: nag

'''DRAFT of new Licensing text as per the discussion at the 9 June 2011 SLOBs meeting'''

Sugar Labs adheres to the principles of Free Software. An [http://www.gnu.org/philosophy/free-sw.html overview of these principles] is found on the [http://gnu.org FSF.org website]. The OSD has a [http://opensource.org/docs/osd set of guidelines for Free and Open Source software] that characterize the intentions of our community.

All software and content distributed by Sugar Labs, including activity bundles uploaded to http://activities.sugarlabs.org, must be released under a license that conforms to the principles and guidelines referred to above.

You may use any license on the Fedora Project's [http://fedoraproject.org/wiki/Licensing#Good_Licenses list of Good Licenses] or the FSF's [http://www.gnu.org/licenses/license-list.html list of Free Software Licenses]. If you wish to use a license not on one of these two lists and believe that it fits our guidelines, please contact the [[Oversight Board]].

----

This policy was determined during a [[Oversight_Board/2009/Meeting_Minutes-2009-12-11#Non-FOSS_content|2009-12-11 board meeting]] and clarified at the [http://meeting.sugarlabs.org/sugar-meeting/2011-06-09#i_2671836 2011-06-09 board meeting].

Please contact the [[Oversight Board]] if you have questions about our licensing policy.

----

+1 to the above text from me! [[User:Bernie|bernie]] 03:29, 15 June 2011 (EDT)

+1 from Cjb, with the fix to one of the links that I just made. [[User:Cjb|Cjb]] 09:45, 15 June 2011 (EDT)

----
''The language seems sloppy to me. Fedora lists both good and bad licenses on the linked page, so saying "You may use any license" from there is not quite what is meant. Secondly, the FSF link goes only to the GNU licenses, perhaps their [http://www.gnu.org/licenses/license-list.html list of Free Software Licenses] is more appropriate?'' [[User:Bert|Bert]] 09:15, 24 June 2011 (EDT)

:Sorry. I realize I had the wrong link. Should be http://www.gnu.org/licenses/license-list.html which includes many non-GNU licenses. --[[User:Walter|Walter]] 09:21, 24 June 2011 (EDT)
:The problem with the Fedora link was a typo. Should link directly to http://fedoraproject.org/wiki/Licensing#Good_Licenses now. --[[User:Walter|Walter]] 09:23, 24 June 2011 (EDT)
:: Maybe just to be explicit, write "Good Licenses" instead of "acceptable licenses"? [[User:Bert|Bert]] 09:54, 24 June 2011 (EDT)
::: Yes. I agree... consistency. --[[User:Walter|Walter]] 10:02, 24 June 2011 (EDT)
''Another nit pick: I find the second link to the GNU.org website distracting and unnecessary. I'd replace ''"is found on the [http://gnu.org GNU.org website]"'' with ''"is provided by the FSF"''. The FSF is mentioned again later, so it's better to use the same name. [[User:Bert|Bert]] 10:04, 24 June 2011 (EDT)
:Nitpicking is right... but I made the change :) --[[User:Walter|Walter]] 10:51, 24 June 2011 (EDT)
:: That's better, though I'd remove that link altogether. It adds nothing to the official Sugar Labs Licensing page. My suggestion was "is provided by the FSF", with no embedded link at all. [[User:Bert|Bert]] 11:11, 24 June 2011 (EDT)
----

+1, having Fedora list of good licences will simplify workflow on ASLO to make it automatic, ie, activities-testing.sugarlabs.org [[Activity_Library/Editors/Policy/Licensing|sees]] to the {{Code|licence}} tag in the {{Code|activitiy.info}} to accept/reject any new upload. [[User:Alsroot|alsroot]] 09:32, 24 June 2011 (EDT)

Talk:Licensing

2011-06-24T14:04:23Z

Bert: suggest rephrasing FSF link

'''DRAFT of new Licensing text as per the discussion at the 9 June 2011 SLOBs meeting'''

Sugar Labs adheres to the principles of Free Software. An [http://www.gnu.org/philosophy/free-sw.html overview of these principles] is found on the [http://gnu.org GNU.org website]. The OSD has a [http://opensource.org/docs/osd set of guidelines for Free and Open Source software] that characterize the intentions of our community.

All software and content distributed by Sugar Labs, including activity bundles uploaded to http://activities.sugarlabs.org, must be released under a license that conforms to the principles and guidelines referred to above.

You may use any license on the Fedora Project's [http://fedoraproject.org/wiki/Licensing#Good_Licenses list of Good Licenses] or the FSF's [http://www.gnu.org/licenses/license-list.html list of Free Software Licenses]. If you wish to use a license not on one of these two lists and believe that it fits our guidelines, please contact the [[Oversight Board]].

----

This policy was determined during a [[Oversight_Board/2009/Meeting_Minutes-2009-12-11#Non-FOSS_content|2009-12-11 board meeting]] and clarified at the [http://meeting.sugarlabs.org/sugar-meeting/2011-06-09#i_2671836 2011-06-09 board meeting].

Please contact the [[Oversight Board]] if you have questions about our licensing policy.

----

+1 to the above text from me! [[User:Bernie|bernie]] 03:29, 15 June 2011 (EDT)

+1 from Cjb, with the fix to one of the links that I just made. [[User:Cjb|Cjb]] 09:45, 15 June 2011 (EDT)

----
''The language seems sloppy to me. Fedora lists both good and bad licenses on the linked page, so saying "You may use any license" from there is not quite what is meant. Secondly, the FSF link goes only to the GNU licenses, perhaps their [http://www.gnu.org/licenses/license-list.html list of Free Software Licenses] is more appropriate?'' [[User:Bert|Bert]] 09:15, 24 June 2011 (EDT)

:Sorry. I realize I had the wrong link. Should be http://www.gnu.org/licenses/license-list.html which includes many non-GNU licenses. --[[User:Walter|Walter]] 09:21, 24 June 2011 (EDT)
:The problem with the Fedora link was a typo. Should link directly to http://fedoraproject.org/wiki/Licensing#Good_Licenses now. --[[User:Walter|Walter]] 09:23, 24 June 2011 (EDT)
:: Maybe just to be explicit, write "Good Licenses" instead of "acceptable licenses"? [[User:Bert|Bert]] 09:54, 24 June 2011 (EDT)
::: Yes. I agree... consistency. --[[User:Walter|Walter]] 10:02, 24 June 2011 (EDT)
''Another nit pick: I find the second link to the GNU.org website distracting and unnecessary. I'd replace ''"is found on the [http://gnu.org GNU.org website]"'' with ''"is provided by the FSF"''. The FSF is mentioned again later, so it's better to use the same name. [[User:Bert|Bert]] 10:04, 24 June 2011 (EDT)
----

+1, having Fedora list of good licences will simplify workflow on ASLO to make it automatic, ie, activities-testing.sugarlabs.org [[Activity_Library/Editors/Policy/Licensing|sees]] to the {{Code|licence}} tag in the {{Code|activitiy.info}} to accept/reject any new upload. [[User:Alsroot|alsroot]] 09:32, 24 June 2011 (EDT)

Talk:Licensing

2011-06-24T13:54:24Z

Bert: suggest link title "Good Licenses"

'''DRAFT of new Licensing text as per the discussion at the 9 June 2011 SLOBs meeting'''

Sugar Labs adheres to the principles of Free Software. An [http://www.gnu.org/philosophy/free-sw.html overview of these principles] is found on the [http://gnu.org GNU.org website]. The OSD has a [http://opensource.org/docs/osd set of guidelines for Free and Open Source software] that characterize the intentions of our community.

All software and content distributed by Sugar Labs, including activity bundles uploaded to http://activities.sugarlabs.org, must be released under a license that conforms to the principles and guidelines referred to above.

You may use any license on the Fedora Project's [http://fedoraproject.org/wiki/Licensing#Good_Licenses list of acceptable licenses] or the FSF's [http://www.gnu.org/licenses/license-list.html list of Free Software licenses]. If you wish to use a license not on one of these two lists and believe that it fits our guidelines, please contact the [[Oversight Board]].

----

This policy was determined during a [[Oversight_Board/2009/Meeting_Minutes-2009-12-11#Non-FOSS_content|2009-12-11 board meeting]] and clarified at the [http://meeting.sugarlabs.org/sugar-meeting/2011-06-09#i_2671836 2011-06-09 board meeting].

Please contact the [[Oversight Board]] if you have questions about our licensing policy.

----

+1 to the above text from me! [[User:Bernie|bernie]] 03:29, 15 June 2011 (EDT)

+1 from Cjb, with the fix to one of the links that I just made. [[User:Cjb|Cjb]] 09:45, 15 June 2011 (EDT)

----
''The language seems sloppy to me. Fedora lists both good and bad licenses on the linked page, so saying "You may use any license" from there is not quite what is meant. Secondly, the FSF link goes only to the GNU licenses, perhaps their [http://www.gnu.org/licenses/license-list.html list of Free Software Licenses] is more appropriate?'' [[User:Bert|Bert]] 09:15, 24 June 2011 (EDT)

:Sorry. I realize I had the wrong link. Should be http://www.gnu.org/licenses/license-list.html which includes many non-GNU licenses. --[[User:Walter|Walter]] 09:21, 24 June 2011 (EDT)
:The problem with the Fedora link was a typo. Should link directly to http://fedoraproject.org/wiki/Licensing#Good_Licenses now. --[[User:Walter|Walter]] 09:23, 24 June 2011 (EDT)
:: Maybe just to be explicit, write "Good Licenses" instead of "acceptable licenses"? [[User:Bert|Bert]] 09:54, 24 June 2011 (EDT)
----

+1, having Fedora list of good licences will simplify workflow on ASLO to make it automatic, ie, activities-testing.sugarlabs.org [[Activity_Library/Editors/Policy/Licensing|sees]] to the {{Code|licence}} tag in the {{Code|activitiy.info}} to accept/reject any new upload. [[User:Alsroot|alsroot]] 09:32, 24 June 2011 (EDT)

Talk:Licensing

2011-06-24T13:15:24Z

Bert: Remark on sloppy language, suggest better FSF link

Emulator image files

2011-06-10T23:11:56Z

Bert: /* Sugar on a Stick v3 Mirabelle */ works only with VirtualBox 3.2

<noinclude>[[Category:Virtual machine or platform emulator]]</noinclude>

==Other virtual machines==

This is a quick guide to the locations of various forms of Sugar software that can run in QEMU emulation or VMware or VirtualBox virtualization.

You can download installation images (.iso files) for Linux distributions that support Sugar and create your own bootable images with Sugar installed.

See [[VirtualBox]], [[VMware]], or [[QEMU]] for more information on how to run an image, and [[Supported systems]] for more information on what is available.


:wikipedia: '''[[wikipedia:Comparison_of_platform_virtual_machines|Comparison of platform virtual machines]]''' - Very nice comparison of features of Virtual Machines platforms
===[[File:VirtualBox.png|75px|link=VirtualBox]]'''[[VirtualBox]]'''===

Latest version: '''VirtualBox 4.0'''

Download: http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html
:''Preliminary testing shows that VirtualBox Appliances from ver 3.1.10-12 import and function well in ver 4.0.x and visa-versa.''

* VirtualBox-4.0 is OSE version until you add: [http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html Oracle VM VirtualBox Extension Pack]
* Support for Windows, Mac OS X, Solaris, and GNU/Linux

* '''VMware Workstation xxx.vmdk Hard Disks will work as "existing Disks" in VirtualBox'''
* [http://www.virtualbox.org/manual/ VirtualBox Manual]
* [http://www.virtualbox.org/manual/ch08.html VBoxManage command line tool for VirtualBox] for advanced users
{{Admon/note|
* '''When making a new VM''', to clear the Sugar Journal of old entries and to avoid identity conflicts among copies of the VM, enter the command {{Code|rm -rf ~/.sugar}} in the Terminal activity. Then shutdown the VM. This will clear all Learner information on the VM and let you start with a fresh install. Skipping this will result in collisions in the Neighborhood view of the Jabber network between separate copies of the appliance. Verify the presence of the '''.sugar''' directory by entering {{Code|ls -a}} in Terminal.
* '''When cloning a customized VM''', in order to keep the Journal and installed .xo Activities, use {{Code|rm ~/.sugar/default/owner.key*}} in the Sugar Terminal, and then shutdown the VM. This leaves the Journal entries and removes only the previous Learner's identity key files.}}

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v3 Mirabelle'''====
:'''Sugar 0.88.0'''
:'''RECOMMENDED'''
::firstboot has not yet run; so a new user name and password will be set for the gdm login on startup for the first time
:How Built:
: '''root=sugarroot'''
: 8-GB Virtual Box hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.vmdk 533M
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.ovf 12K

*Note1:Use a later version of Oracle VM VirtualBox (3.2_10.8-64453 or later). Some appliances have multiple hard disc controllers and the earlier Sun VirtualBox 3.1 version does not support them. ''On a Mac this did not work with VirtualBox 4.0 for me. VirtualBox 3.2.12 was fine [http://www.virtualbox.org/wiki/Download_Old_Builds_3_2])''
*Note2: All appliances were built on a MacBook Air with Oracle VM VirtualBox (3.2.10-r66523) then tested on a Ubuntu installation on an Acer Aspire One Netbook imported into VirtualBox (3.2.10 r66523)
*Note3:Set ControlPanel/Frame "Edge" slider to far left for easier access to sugar-frame features

* '''VMware Player Version'''
:[http://people.sugarlabs.org/Tgillard/Soas-v3-Mirabelle.zip Soas-v3-Mirabelle.zip Download]

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v4 Mango Lassi'''====
:'''Sugar 0.90.1''' ''Note Sugar 0.90.x is buggy, use a version of SoaS with the 0.88.1 version.''

:user=sugar
:password=sugaruser
: '''root=sugarroot'''
:How Built:
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Fedora-14-i686-Live-SoaS-2.ovf 12K
http://download.sugarlabs.org/images/VirtualBox/Fedora-14-i686-Live-SoaS-2-disk1.vmdk 606M

:'''had to modify the .ovf to get the image running on a X60 with ubuntu maverick:'''
http://people.sugarlabs.org/dogi/virtualbox/Fedora-14-i686-Live-SoaS-2.1.ovf 12K

*Note, this appliance has 1024x768 screensize available as VirtualBox extensions were compiled into the kernel.

=====To Update Sugar=====
:Sugar update does not work in control panel
* In root sugar-terminal:
yum groupinstall sugar-desktop
: (install 9 packages, Upgrade 10 packages) 02/02/2011 satellit

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v5 Coconut'''====
:'''sugar 0.92.1'''
::'''this is the RC3 version; for testing only at this time'''
; Nightly compose .iso no longer available
:user=sugar
:password=sugaruser
: '''root=sugarroot'''
:How Built:
:liveinst in root terminal to VirtualBox HD
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''Cleared of Identity- starts at click to change color after gdm login'''
::Etoys fixed so it starts
::sub-menus work on activities
::Jabber fills up with duplicate avitars that constantly change colors en-mass.
::http://bugs.sugarlabs.org/ticket/2845
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Soas-v5_RC3_Live_CE.ovf 12.5KB
http://download.sugarlabs.org/images/VirtualBox/Soas-v5_RC3_Live_CE-disk1.vmdk 621 MB
*Login at gdm: sugaruser
; TO UPDATE
sugar-terminal
su
password: sugarroot
yum update
*Problems: f1 Neighborhood does not see Jabber

====f15-Gnome3-Ver3.0.0-Virtual Box-Appliance====
*download these 2 files and import them:
:http://people.sugarlabs.org/Tgillard/F15-gnome3_Desktop_sugar_cl-disk1.vmdk
:http://people.sugarlabs.org/Tgillard/F15-gnome3_Desktop_sugar_cl.ovf
; Starts in gnome3 fallback mode as VirtualBox does not support hardware acceleration
::user=sugar
::password=sugaruser
::root=sugarroot
:Cleared of sugar identity' starts on select color by clicking on XO icon
:use <== arrow to write your custom name then ==> to finish
*Sugar-emulator is in Activities/Education/Sugar
:::enter user password for keychain (sugaruser) on time and cancel until pop-up finishes (this is a bug in keychain in f15)
:Surf-115 is the browser as Browse-120 does not start (known bug)

====f14-SoaS====
*download these 2 files and import them:
:http://people.sugarlabs.org/Tgillard/Fedora_14_SoaS.ovf
:http://people.sugarlabs.org/Tgillard/Fedora_14_SoaS-disk1.vmdk
::user=sugar
::password=sugaruser
::root=sugarroot
*firstboot has not yet been run.
:Sugar on a Stick 4 (Mango Lassi)
:sugar: 0.90.1
*Bugs:
:: Control Panel/Software Update does not work.
:: Delay in start (edit to uncheck floppy disk)

====[[File:trisquel_logo.png]][http://people.sugarlabs.org/Tgillard/Trisquel41_sugar_installer.iso Trisquel41_sugar INSTALLER ISO][[File:CD.png]]====

:Revised 03/02/2011 to remove sugar identity
:'''RECOMMENDED'''
*click above link^ to download 1.2GB DVD which contains
32bit-VirtualBox Installers (OSE) (Directory with install files for VirtualBox 4.0.4)
'''(Does not include Free for Personal Use licensed extension pack)''' - includes instructions on how to download them for personal use.
ReadMeFirst_Install_Instructions.pdf (Instructions-how to install VirtualBox and import appliance)
trisquel-sugar-4.1-i686-feb18.ovf
trisquel-sugar-4.1-i686-feb18-disk1.vmdk
UserManual.pdf (VirtualBox 4.0.4 User Manual-269 pages)
: Instructions and .vmdk/.ovf files to import
* Cleared of sugar identity Starts on Color Selection Screen ( <===(back) to change name)
{{Admon/faq|Question|Does this contain Oracle VirtualBox binaries that are not redistributable under their [http://www.virtualbox.org/wiki/Licensing_FAQ licensing]? We may need their permission to redistribute some of their software. '''see listing above of contents for answer'''}}

====[[File:Trisquel_icon.png]] Trisquel-Gnome-sugar 4.5 Release Candidate====
::[http://devel2.trisquel.info/slaine/iso/ trisquel 4.5 Download]
: XChat; sweets-sugar 0.88.1; surf115-xo; updated; cleared of identity; autostart
::User=sugar
::password sugaruser
*"Free Distibution"
*Ubuntu 10.10 based
* Trisquel 4.5 RC VirtualBox 4.0.4 appliance
:Download and Import these files:
http://people.sugarlabs.org/Tgillard/trisquel_4.5-RC_i686surf115-cleared.ovf
http://people.sugarlabs.org/Tgillard/trisquel_4.5-RC_i686surf115-cleared-disk1.vmdk

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.5 -Gnome-sugar BETA|Trisquel-4.5 -Gnome-sugar BETA]]====
:(click this ^ link for details)
* Gnome and Sugar 0.88.1
*: Beta, so not for Production use, but quite stable for testing
* [http://devel2.trisquel.info/slaine/iso/ Trisquel 4.5 Download]
*:[[Community/Distributions/Trisquel]]

* Sugar sweets 0.88.1 with 30 applications: [[Trisquel_On_A_Sugar_Toast#Install_Sugar-desktop_0.88_.22SWEETS.22|How to install sweets-sugar-desktop 0.88.1]]
*: Updated 02/04/2011 (System/Administration/Update Manager)

* download and import 2 files:
*# http://people.sugarlabs.org/Tgillard/Tris-45-Sugar0801-4.ovf 13K
*# http://people.sugarlabs.org/Tgillard/Tris-45-Sugar0801-4-disk1.vmdk 1.4G

*NOTE: This is a Beta version. A lot of updates are still coming in.
*: Sugar 0.88.1 is a much more stable release than sugar 0.90.1

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.1-sugar|Trisquel-4.1-sugar]]====
:(click this ^ link for details)
:'''RECOMMENDED'''
* Sugar sweets 0.88.1
*:NEW: 02/18/2011 2nd Beta Version with application fixes
*:[[Community/Distributions/Trisquel]]

* download and import 2 files:
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned-disk1.vmdk
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned.ovf

* Cleared of sugar identity Starts on Color Selection Screen ( <===(back) to change name) 03/02/2011

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.0.1-Gnome-sugar|Trisquel-4.0.1-Gnome-sugar]]====
:(click this ^ link for details)
* Gnome and Sugar 0.90.1
*:[[Community/Distributions/Trisquel]]

* Updated 12/23/2010

* download and import 2 files:
*# http://download.sugarlabs.org/images/VirtualBox/trisquel_4.0.1_ext4-sugar0901.ovf 13K
*# http://download.sugarlabs.org/images/VirtualBox/trisquel_4.0.1_ext4.vmdk 2.1 GB

* VMware Player Version
*:[http://download.sugarlabs.org/images/vmplayer/Trisquel-4-sugar-VMPlayer.zip Trisquel-4-sugar-VMPlayer Download]

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-3-sugar|Trisquel-3-sugar]]====
:(click this ^ link for details)
* Sugar 0.86.2
*:[[Community/Distributions/Trisquel]]

* download and import 2 files:
*# http://download.sugarlabs.org/images/VirtualBox/Trisquel-3-sugar-sugaruser.vmdk 543M
*# http://download.sugarlabs.org/images/VirtualBox/Trisquel-3-sugar-sugaruser.ovf 12K

* VMware Player Version
*:[http://download.sugarlabs.org/images/vmplayer/Trisquel3.zip Trisquel3.zip Download]

* '''20 new applications were installed by CP/software update'''

====[[Image:Debian-small.jpg]]'''Debian-squeeze-Gnome-sugar'''====
::'''Full Gnome Desktop plus Sugar 0.88.1'''
::[http://wiki.sugarlabs.org/go/Community/Distributions/Debian Debian Information]
:Updated 12/05/2010 includes activities Downloaded from ASLO as .xo files; and sugar-emulator.
::Log in as sugar
::password=sugaruser
::root=sugarroot
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Debian-sugaruser.vmdk 2.1G
http://download.sugarlabs.org/images/VirtualBox/Debian-sugaruser-1.ovf 14K

====[[Image:Mandriva-small.png]]'''Mandriva-linux-one-2010.1-Gnome-sugar'''====
::'''Full Gnome Desktop plus Sugar-0.88.0'''
::[http://wiki.sugarlabs.org/go/Community/Distributions/Mandriva Mandriva Information]
:::Note Log into gnome desktop first to enable networking then start sugar-emulator
::Log in as sugar
::password=sugaruser
::root=sugaruser
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
download and import 2 files:
http://download.sugarlabs.org/images/VirtualBox/mandriva-linux-one-2010-sugaruser-plus.ovf 14K
http://download.sugarlabs.org/images/VirtualBox/mandriva-linux-one-2010.vmdk 1.4G

Info:
: [http://www2.mandriva.com/downloads/free/ 2010.2 free DVD Download]
: [http://wiki.mandriva.com/en/Mandriva_Linux_2010.1 Mandriva_Linux_2010.1 Download]
: [http://www2.mandriva.com/en/linux/overview/ Mandriva 2010.1 Features]
: [http://www2.mandriva.com/en/news/?p=145&s=0 The Brazilian government education authority has selected Intel-powered classmate PCs running Mandriva Linux for educational use nationwide.]

'''[[:File:MacBook_Air-Virtualbox.jpg|Photo of Neighborhood view on MacBook Air-Mandriva 2010.1]]'''

*Note: The above appliances were built on a MacBook Air with Oracle VM VirtualBox (3.2.10-r66523) then tested on a Ubuntu installation on an Acer Aspire One Netbook imported into VirtualBox (3.2.10 r66523)

====Some Suggestions on Using VirtualBox====
* Export your appliances to an external USB hard disk
*: This functions like the Mac Application "Time Machine"
*: Save each exported Appliance in a folder marked with the name and date of export.
*::You can then import this Appliance to restore the state of the Appliance on that date.

*Run an Existing VirtualBox Appliance from an external USB Hard Drive
*::Portable, Individual Copy for Student, Move between separate Computers.
*# copy-paste the xxxx.vmdk file from /(User)/Virtualbox/HardDisks/xxxx.vmdk to a Folder on an external USB HD
*# Menu: Machine>New>continue>Name>Operating System>Version/Memory/Continue>Use existing hard disk>[chose xxxx.vmdk on an External USB HD]> Start.

* Note Running from a USB Memory Stick Crawls, VERY slowly - '''not practical'''.

*'''Testing of appliance running from an external USB Hard Disk
:: Appears to depend on the Speed of the Host Machine: (needs farther testing)
# Very Slow - Fedora-13-Soas/VB 3.2.12 on Windows XP SP2/ EeePC 1000HE 12/26/2010 satellit
# Very Slow - Trisquel-3-sugar/VB 3.2.12 on Windows XP SP2/ EeePC 1000HE 12/26/2010 satellit
# Acceptable- Fedora-13-Soas/VB 4.0 on Ubuntu 10.10 /hp Pavillion Turion 64x2 laptop 12/26/2010 satellit
# Acceptable- Trisquel-3-sugar/VB 4.0 on Ubuntu 10.10 /hp Pavillion Turion 64x2 laptop 12/26/2010 satellit

===='''Join IRC for Help'''====

* '''[http://webchat.freenode.net/?randomnick=1&channels=sugar&prompt=1 Join Sugar chat room for Help in English]'''
*'''[http://webchat.freenode.net/?randomnick=1&channels=sugar-es&prompt=1 Sugar chat room in Español]''' (with translations to English)
Pida ayuda a través de este canal #sugar-es Por favor, sea cortés y hacer sus preguntas.
Los voluntarios no pueden estar en línea todo el tiempo.
Sea paciente y permanecer conectado durante varios minutos para ver su respuest
:::(utilizar la función de meeting para la traducción de estos artículos)

: Ask for help on either of these channels.
:: Please be courteous and ask your questions.
:: Volunteers may not be on line all of the time. Be patient and stay connected for several minutes to see their answer.
* '''Read the [[Sugar_Creation_Kit#Floss_Manuals| Floss Manuals]] first!'''

====References====
:http://www.virtualbox.org/manual/ch03.html#id2727661 [Configuring virtual machines]
:http://www.virtualbox.org/manual/ch03.html#id321700 [USB Support]
:[http://www.virtualbox.org/manual/ Oracle VM VirtualBox online Manual]
:[http://download.virtualbox.org/virtualbox/UserManual.pdf UserManual.pdf]

====Extension Pack====
:[http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html Oracle VM VirtualBox Extension Pack] '''Personal Use License'''
::All Platforms (Windows, Mac OS X, Solaris and Linux)
* '''Personal Use Licensed not OSE'''

==='''[[VMware]] Player'''===
[https://www.vmware.com/tryvmware/?p=player&lp=default Download VMware Player (free)]

* VMware Player appliance of soas-v3-Mirabelle
:Compressed in .zip file
:[http://people.sugarlabs.org/Tgillard/Soas-v3-Mirabelle.zip Download]
::This appliance is ready to run "firstboot" (agree/user name/password/tz/etc)
::'''sugarroot''' is the root password.

* VMware Player appliance Trisquel-3 (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel3.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Trisquel-4+sugar (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel-4-sugar-VMPlayer.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Sugar on a Stick v2 (Blueberry)
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.txt Read this first.]
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.tar.gz download]

* VMware Player appliance of openSUSE-Sugar
:[[VMware#openSUSE |Read this first.]]
:[http://sourceforge.net/projects/opensuse-edu/files/Sugar/openSUSE-Sugar-vmware-vmx.tar.bz2/download download]
:[[Talk:VMware#change_networking|networking help]]
:[http://old-en.opensuse.org/How_to_use_downloaded_SUSE_Studio_appliances how to use]

===Older Virtual Appliances===

'''Hint for the following Appliances: when Downloading xxxx.mf and xxxx.ovf files use "save as" to download then hit < on browser to return to previous screen in browser'''

*'''Sugar on a Stick v2 Bluberry'''
:link: [[Sugar on a Stick/Blueberry|Blueberry]] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry_ovf_README_FIRST.txt Read this first.]
:'''download and import 3 files''': [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.ovf soas-2-blueberry.ovf] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.mf soas-2-blueberry.mf] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.vmdk soas-2-blueberry.vmdk]

*'''Sugar on a Stick v1 Strawberry'''
:Link: [[Sugar on a Stick/Strawberry|Strawberry]]
: [http://www.sugarlabs.org/static/soas/soas-strawberry-vdi.zip soas-strawberry-vdi.zip] Sugar 0.84 (22 June 2009)
::This is a compressed VirtualBox Hardisk. Decompress it and Create a new VirtualBox Appliance that points to this '''existing .vdi Hard Disk''' not a new one.
::'''[http://wiki.sugarlabs.org/go/Talk:Emulator_image_files#How_to_Update_Soas-v1-Strawberry-vdi How_to_Update_Soas-v1-Strawberry-vdi Activities]'''

*'''openSUSE-Sugar-11.3'''
: Reference links: [http://download.opensuse.org/repositories/Education/images/iso/openSUSE-Sugar-11.3.i686-1.0.0-Build6.3.iso openSUSE-Sugar-11.3.i686-1.0.0-Build6.3.iso] Uploaded 26 September 2010 
:'''download and import 3 files''':openSUSE_sugar.ovf [http://people.sugarlabs.org/Tgillard/openSUSE_sugar.ovf openSUSE_sugar.ovf] [http://people.sugarlabs.org/Tgillard/openSUSE_sugar.mf openSUSE_sugar.mf] [http://people.sugarlabs.org/Tgillard/openSUSE-Sugar-11.3.vmdk openSUSE-Sugar-11.3.vmdk]
::8-GB VirtualBox hard disc
::English and English keyboard
::USA-Los Angeles (Pacific timezone)
::Autologin- user=sugar password=sugaruser
:::Ready to auto-configure to your hardware on first booting.
:::'''note choose /dev/sda2 when prompted to do so on first run'''

*'''U'''buntu'''S'''ugar'''''R'''emix''
: Reference links: [[Community/Distributions/Ubuntu]], https://wiki.ubuntu.com/Sugar
::''shutdown does nothing from sugar; To exit sugar use "Log Out" then shutdown from bottom right gdm bar''

:'''download and import 3 files''': [http://people.sugarlabs.org/Tgillard/USR-922-IRC-Remix.ovf USR-922-IRC-Remix.ovf] [http://people.sugarlabs.org/Tgillard/USR-922-IRC-Remix.mf USR-922-IRC-Remix.mf] [http://people.sugarlabs.org/Tgillard/USR-i386-20100922.vmdk USR-i386-20100922.vmdk]
::TZ=LA USA USA Keyboard 8-GB HD fully updated on 22 September 2010 with
::apt-get Updates
::apt-get Upgrade
::Remixed to add
:::Surf-115.xo browser
:::IRC.xo -(edited to log in to #sugar and #ubuntu-sugarteam)
:::Analyze.xo
:::'''Import the 3 files into Oracle VirtualBox'''
::: User=sugar autologin
::: Password=sugaruser
*'''install the VirtualBox guest additions'''
::Integrates a Running VirtualBox Appliance with the desktop
:install the VirtualBox guest additions with ''sudo apt-get install virtualbox-ose-guest-utils''
==='''[[QEMU]]'''===
:[[Sugar_Creation_Kit#QEMU_Virtualization|instructions, downloads]]

== Image installation tools ==
==='''[[Sugar_on_a_Stick/ZyX-LiveInstaller|ZyX-LiveInstaller]]'''===
* ZyX-LiveInstaller allows you to install Sugar from either a booted Live USB device,
* or Live CD media to a system or external disk.
* It creates an exact copy of your running live CD as a traditional (Persistent) installation on your hard-disk (or removable media such as SD or USB storage devices.
: This program can be useful for installing to a virtualized hard disk. It is not included in builds after soas-v2 Blueberry, so it must be downloaded and installed to use.
: In a running SoaS Terminal session or console, execute the following commands:
: {{Code|su}}
: {{Code|yum install zyx-liveinstaller gparted}}

===[http://www.easyvmx.com EasyVMX!]===
:'''Make a VirtualBox or VMware Player appliance with a burned CD of your favorite xxx.iso'''

* '''http://www.easyvmx.com/ is a web site that builds a vmx file to your specifications (free).'''

: Works fine, runs on most platforms, and has persistence after installation. (tested with Trisquel 4.0.1 DVD 12/24/2010 satellit)
:: Virtual Appliance that you create Can be opened with either VirtualBox or VMware Player
: VirtualBox 4.0 Download (free): http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html
: VMware Player download (free): http://www.vmware.com/tryvmware/
:::(Note:VMware Workstation not needed for VMware Player to create Virtual Appliance)

::specified a 8 GB Hard Drive; name; and other parameters
::downloaded, in browse, the Custom vmx file as a .zip file
::Decompressed the .zip file

: Insert the CD of your favorite xxx.iso

::Open VirtualBox4.0 or VMware Player and point it to this vmx file
:::In VirtualBox Settings/specify CD Player (/dev/sr0); Start
:::VMware Player starts CD automatically

* EXAMPLE: soas-i386-20100926.17.iso burned to a CD
::Put soas-i386-20100926.17 CD in your CD Drive
::CD boots in VirtualBox-4.0 or VMware Player application
::Sugar Starts

*To install to EasyVMX Hard Disk:
:Open Sugar-terminal:
su
liveinst
Anaconda installer opens
Initialize all disks
Install procedes normally
reboot
firstboot
Log in to user you specified

'''HINT: copy all of the EasyVMX Hard Disk Files on a 2 GB USB stick.'''
::'''(note runs about 10x slower on a USB stick)'''
::Example above created a 1.4 GB set of files'
:Copy-Paste all files
: Sugar on a Stick in VirtualBox or VMware Player Hard Disk format with persistence
::Portable (Student can take home and run on home Computer)
::Run it on different Platforms

==Click for: [[Talk:Emulator image files|More Discussions]]==

==References==
* [[Mac OS X-Boot USB with VirtualBox]]
* [http://lists.laptop.org/pipermail/devel/2008-September/019643.html Tom van Overbeek describes how to run Sugar using QEMU]
* [https://fedoraproject.org/wiki/Features/BoxGrinder BoxGrinder: a set of tools used for building appliances (virtual machines)]
* [http://fedoraproject.org/wiki/Licensing Licensing-License types and info for exported Appliances-]

== Thanks ==

Thanks for this work satellit_, emulators are a great way to develop and test stuff. --[[User:RafaelOrtiz|RafaelOrtiz]] 17:19, 13 April 2011 (EDT)

Emulator image files

2011-05-16T15:18:42Z

Bert: /* VirtualBox */ fix command to reset sugar

<noinclude>[[Category:Virtual machine or platform emulator]]</noinclude>

==Other virtual machines==

This is a quick guide to the locations of various forms of Sugar software that can run in QEMU emulation or VMware or VirtualBox virtualization.

You can download installation images (.iso files) for Linux distributions that support Sugar and create your own bootable images with Sugar installed.

See [[VirtualBox]], [[VMware]], or [[QEMU]] for more information on how to run an image, and [[Supported systems]] for more information on what is available.


:wikipedia: '''[[wikipedia:Comparison_of_platform_virtual_machines|Comparison of platform virtual machines]]''' - Very nice comparison of features of Virtual Machines platforms
===[[File:VirtualBox.png|75px|link=VirtualBox]]'''[[VirtualBox]]'''===

Latest version: '''VirtualBox 4.0'''

Download: http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html
:''Preliminary testing shows that VirtualBox Appliances from ver 3.1.10-12 import and function well in ver 4.0.x and visa-versa.''

* VirtualBox-4.0 is OSE version until you add: [http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html Oracle VM VirtualBox Extension Pack]
* Support for Windows, Mac OS X, Solaris, and GNU/Linux

* '''VMware Workstation xxx.vmdk Hard Disks will work as "existing Disks" in VirtualBox'''
* [http://www.virtualbox.org/manual/ VirtualBox Manual]
* [http://www.virtualbox.org/manual/ch08.html VBoxManage command line tool for VirtualBox] for advanced users
{{Admon/note|
* '''When making a new VM''', to clear the Sugar Journal of old entries and to avoid identity conflicts among copies of the VM, enter the command {{Code|rm -rf ~/.sugar}} in the Terminal activity. Then shutdown the VM. This will clear all Learner information on the VM and let you start with a fresh install. Skipping this will result in collisions in the Neighborhood view of the Jabber network between separate copies of the appliance. Verify the presence of the '''.sugar''' directory by entering {{Code|ls -a}} in Terminal.
* '''When cloning a customized VM''', in order to keep the Journal and installed .xo Activities, use {{Code|rm ~/.sugar/default/owner.key*}} in the Sugar Terminal, and then shutdown the VM. This leaves the Journal entries and removes only the previous Learner's identity key files.}}

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v3 Mirabelle'''====
:'''Sugar 0.88.0'''
:'''RECOMMENDED'''
::firstboot has not yet run; so a new user name and password will be set for the gdm login on startup for the first time
:How Built:
: '''root=sugarroot'''
: 8-GB Virtual Box hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.vmdk 533M
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.ovf 12K

*Note1:Use a later version of Oracle VM VirtualBox (3.2_10.8-64453 or later). Some appliances have multiple hard disc controllers and the earlier Sun VirtualBox 3.1 version does not support them.
*Note2: All appliances were built on a MacBook Air with Oracle VM VirtualBox (3.2.10-r66523) then tested on a Ubuntu installation on an Acer Aspire One Netbook imported into VirtualBox (3.2.10 r66523)
*Note3:Set ControlPanel/Frame "Edge" slider to far left for easier access to sugar-frame features

* '''VMware Player Version'''
:[http://people.sugarlabs.org/Tgillard/Soas-v3-Mirabelle.zip Soas-v3-Mirabelle.zip Download]

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v4 Mango Lassi'''====
:'''Sugar 0.90.1''' ''Note Sugar 0.90.x is buggy, use a version of SoaS with the 0.88.1 version.''

:user=sugar
:password=sugaruser
: '''root=sugarroot'''
:How Built:
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Fedora-14-i686-Live-SoaS-2.ovf 12K
http://download.sugarlabs.org/images/VirtualBox/Fedora-14-i686-Live-SoaS-2-disk1.vmdk 606M

:'''had to modify the .ovf to get the image running on a X60 with ubuntu maverick:'''
http://people.sugarlabs.org/dogi/virtualbox/Fedora-14-i686-Live-SoaS-2.1.ovf 12K

*Note, this appliance has 1024x768 screensize available as VirtualBox extensions were compiled into the kernel.

=====To Update Sugar=====
:Sugar update does not work in control panel
* In root sugar-terminal:
yum groupinstall sugar-desktop
: (install 9 packages, Upgrade 10 packages) 02/02/2011 satellit

====[[Image:Fedora-small.jpg]]'''Sugar on a Stick v5 Coconut'''====
:'''sugar 0.92.1'''
::'''this is the RC3 version; for testing only at this time'''
:http://alt.fedoraproject.org/pub/alt/stage/15.RC3/Live/i686/Fedora-15-i686-Live-SoaS.iso
:user=sugar
:password=sugaruser
: '''root=sugarroot'''
:How Built:
:liveinst in root terminal to VirtualBox HD
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''Cleared of Identity- starts at click to change color after gdm login'''
::Etoys fixed so it starts
::sub-menus work on activities
::Jabber fills up with duplicate avitars that constantly change colors en-mass.
::http://bugs.sugarlabs.org/ticket/2845
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Soas-v5_RC3_Live_CE.ovf 12.5KB
http://download.sugarlabs.org/images/VirtualBox/Soas-v5_RC3_Live_CE-disk1.vmdk 621 MB

====f15-Gnome3-Ver3.0.0-Virtual Box-Appliance====
*download these 2 files and import them:
:http://people.sugarlabs.org/Tgillard/F15-gnome3_Desktop_sugar_cl-disk1.vmdk
:http://people.sugarlabs.org/Tgillard/F15-gnome3_Desktop_sugar_cl.ovf
; Starts in gnome3 fallback mode as VirtualBox does not support hardware acceleration
::user=sugar
::password=sugaruser
::root=sugarroot
:Cleared of sugar identity' starts on select color by clicking on XO icon
:use <== arrow to write your custom name then ==> to finish
*Sugar-emulator is in Activities/Education/Sugar
:::enter user password for keychain (sugaruser) on time and cancel until pop-up finishes (this is a bug in keychain in f15)
:Surf-115 is the browser as Browse-120 does not start (known bug)

====f14-SoaS====
*download these 2 files and import them:
:http://people.sugarlabs.org/Tgillard/Fedora_14_SoaS.ovf
:http://people.sugarlabs.org/Tgillard/Fedora_14_SoaS-disk1.vmdk
::user=sugar
::password=sugaruser
::root=sugarroot
*firstboot has not yet been run.
:Sugar on a Stick 4 (Mango Lassi)
:sugar: 0.90.1
*Bugs:
:: Control Panel/Software Update does not work.
:: Delay in start (edit to uncheck floppy disk)

====[[File:trisquel_logo.png]][http://people.sugarlabs.org/Tgillard/Trisquel41_sugar_installer.iso Trisquel41_sugar_installer.iso]====
:Revised 03/02/2011 to remove sugar identity
:'''RECOMMENDED'''
*click above link^ to download 1.2GB DVD which contains
32bit-VirtualBox Installers (OSE) (Directory with install files for VirtualBox 4.0.4)
(Does not include Free for Personal Use licensed extension pack) - includes instructions on how to download for personal use.
ReadMeFirst_Install_Instructions.pdf (Instructions-how to install VirtualBox and import appliance)
trisquel-sugar-4.1-i686-feb18.ovf
trisquel-sugar-4.1-i686-feb18-disk1.vmdk
UserManual.pdf (VirtualBox 4.0.4 User Manual-269 pages)
: Instructions and .vmdk/.ovf files to import
* Cleared of sugar identity Starts on Color Selection Screen ( <===(back) to change name)
{{Admon/faq|Question|Does this contain Oracle VirtualBox binaries that are not redistributable under their [http://www.virtualbox.org/wiki/Licensing_FAQ licensing]? We may need their permission to redistribute some of their software. see listing above of contents for answer}}

====[[File:Trisquel_icon.png]] Trisquel-Gnome-sugar 4.5 Release Candidate====
::[http://devel2.trisquel.info/slaine/iso/ trisquel 4.5 Download]
: XChat; sweets-sugar 0.88.1; surf115-xo; updated; cleared of identity; autostart
::User=sugar
::password sugaruser
*"Free Distibution"
*Ubuntu 10.10 based
* Trisquel 4.5 RC VirtualBox 4.0.4 appliance
:Download and Import these files:
http://people.sugarlabs.org/Tgillard/trisquel_4.5-RC_i686surf115-cleared.ovf
http://people.sugarlabs.org/Tgillard/trisquel_4.5-RC_i686surf115-cleared-disk1.vmdk

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.5 -Gnome-sugar BETA|Trisquel-4.5 -Gnome-sugar BETA]]====
:(click this ^ link for details)
* Gnome and Sugar 0.88.1
*: Beta, so not for Production use, but quite stable for testing
* [http://devel2.trisquel.info/slaine/iso/ Trisquel 4.5 Download]
*:[[Community/Distributions/Trisquel]]

* Sugar sweets 0.88.1 with 30 applications: [[Trisquel_On_A_Sugar_Toast#Install_Sugar-desktop_0.88_.22SWEETS.22|How to install sweets-sugar-desktop 0.88.1]]
*: Updated 02/04/2011 (System/Administration/Update Manager)

* download and import 2 files:
*# http://people.sugarlabs.org/Tgillard/Tris-45-Sugar0801-4.ovf 13K
*# http://people.sugarlabs.org/Tgillard/Tris-45-Sugar0801-4-disk1.vmdk 1.4G

*NOTE: This is a Beta version. A lot of updates are still coming in.
*: Sugar 0.88.1 is a much more stable release than sugar 0.90.1

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.1-sugar|Trisquel-4.1-sugar]]====
:(click this ^ link for details)
:'''RECOMMENDED'''
* Sugar sweets 0.88.1
*:NEW: 02/18/2011 2nd Beta Version with application fixes
*:[[Community/Distributions/Trisquel]]

* download and import 2 files:
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned-disk1.vmdk
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned.ovf

* Cleared of sugar identity Starts on Color Selection Screen ( <===(back) to change name) 03/02/2011

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-4.0.1-Gnome-sugar|Trisquel-4.0.1-Gnome-sugar]]====
:(click this ^ link for details)
* Gnome and Sugar 0.90.1
*:[[Community/Distributions/Trisquel]]

* Updated 12/23/2010

* download and import 2 files:
*# http://download.sugarlabs.org/images/VirtualBox/trisquel_4.0.1_ext4-sugar0901.ovf 13K
*# http://download.sugarlabs.org/images/VirtualBox/trisquel_4.0.1_ext4.vmdk 2.1 GB

* VMware Player Version
*:[http://download.sugarlabs.org/images/vmplayer/Trisquel-4-sugar-VMPlayer.zip Trisquel-4-sugar-VMPlayer Download]

====[[File:Trisquel_icon.png]][[/Trisquel#Trisquel-3-sugar|Trisquel-3-sugar]]====
:(click this ^ link for details)
* Sugar 0.86.2
*:[[Community/Distributions/Trisquel]]

* download and import 2 files:
*# http://download.sugarlabs.org/images/VirtualBox/Trisquel-3-sugar-sugaruser.vmdk 543M
*# http://download.sugarlabs.org/images/VirtualBox/Trisquel-3-sugar-sugaruser.ovf 12K

* VMware Player Version
*:[http://download.sugarlabs.org/images/vmplayer/Trisquel3.zip Trisquel3.zip Download]

* '''20 new applications were installed by CP/software update'''

====[[Image:Debian-small.jpg]]'''Debian-squeeze-Gnome-sugar'''====
::'''Full Gnome Desktop plus Sugar 0.88.1'''
::[http://wiki.sugarlabs.org/go/Community/Distributions/Debian Debian Information]
:Updated 12/05/2010 includes activities Downloaded from ASLO as .xo files; and sugar-emulator.
::Log in as sugar
::password=sugaruser
::root=sugarroot
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Debian-sugaruser.vmdk 2.1G
http://download.sugarlabs.org/images/VirtualBox/Debian-sugaruser-1.ovf 14K

====[[Image:Mandriva-small.png]]'''Mandriva-linux-one-2010.1-Gnome-sugar'''====
::'''Full Gnome Desktop plus Sugar-0.88.0'''
::[http://wiki.sugarlabs.org/go/Community/Distributions/Mandriva Mandriva Information]
:::Note Log into gnome desktop first to enable networking then start sugar-emulator
::Log in as sugar
::password=sugaruser
::root=sugaruser
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
download and import 2 files:
http://download.sugarlabs.org/images/VirtualBox/mandriva-linux-one-2010-sugaruser-plus.ovf 14K
http://download.sugarlabs.org/images/VirtualBox/mandriva-linux-one-2010.vmdk 1.4G

Info:
: [http://www2.mandriva.com/downloads/free/ 2010.2 free DVD Download]
: [http://wiki.mandriva.com/en/Mandriva_Linux_2010.1 Mandriva_Linux_2010.1 Download]
: [http://www2.mandriva.com/en/linux/overview/ Mandriva 2010.1 Features]
: [http://www2.mandriva.com/en/news/?p=145&s=0 The Brazilian government education authority has selected Intel-powered classmate PCs running Mandriva Linux for educational use nationwide.]

'''[[:File:MacBook_Air-Virtualbox.jpg|Photo of Neighborhood view on MacBook Air-Mandriva 2010.1]]'''

*Note: The above appliances were built on a MacBook Air with Oracle VM VirtualBox (3.2.10-r66523) then tested on a Ubuntu installation on an Acer Aspire One Netbook imported into VirtualBox (3.2.10 r66523)

====Some Suggestions on Using VirtualBox====
* Export your appliances to an external USB hard disk
*: This functions like the Mac Application "Time Machine"
*: Save each exported Appliance in a folder marked with the name and date of export.
*::You can then import this Appliance to restore the state of the Appliance on that date.

*Run an Existing VirtualBox Appliance from an external USB Hard Drive
*::Portable, Individual Copy for Student, Move between separate Computers.
*# copy-paste the xxxx.vmdk file from /(User)/Virtualbox/HardDisks/xxxx.vmdk to a Folder on an external USB HD
*# Menu: Machine>New>continue>Name>Operating System>Version/Memory/Continue>Use existing hard disk>[chose xxxx.vmdk on an External USB HD]> Start.

* Note Running from a USB Memory Stick Crawls, VERY slowly - '''not practical'''.

*'''Testing of appliance running from an external USB Hard Disk
:: Appears to depend on the Speed of the Host Machine: (needs farther testing)
# Very Slow - Fedora-13-Soas/VB 3.2.12 on Windows XP SP2/ EeePC 1000HE 12/26/2010 satellit
# Very Slow - Trisquel-3-sugar/VB 3.2.12 on Windows XP SP2/ EeePC 1000HE 12/26/2010 satellit
# Acceptable- Fedora-13-Soas/VB 4.0 on Ubuntu 10.10 /hp Pavillion Turion 64x2 laptop 12/26/2010 satellit
# Acceptable- Trisquel-3-sugar/VB 4.0 on Ubuntu 10.10 /hp Pavillion Turion 64x2 laptop 12/26/2010 satellit

===='''Join IRC for Help'''====

* '''[http://webchat.freenode.net/?randomnick=1&channels=sugar&prompt=1 Join Sugar chat room for Help in English]'''
*'''[http://webchat.freenode.net/?randomnick=1&channels=sugar-es&prompt=1 Sugar chat room in Español]''' (with translations to English)
Pida ayuda a través de este canal #sugar-es Por favor, sea cortés y hacer sus preguntas.
Los voluntarios no pueden estar en línea todo el tiempo.
Sea paciente y permanecer conectado durante varios minutos para ver su respuest
:::(utilizar la función de meeting para la traducción de estos artículos)

: Ask for help on either of these channels.
:: Please be courteous and ask your questions.
:: Volunteers may not be on line all of the time. Be patient and stay connected for several minutes to see their answer.
* '''Read the [[Sugar_Creation_Kit#Floss_Manuals| Floss Manuals]] first!'''

====References====
:http://www.virtualbox.org/manual/ch03.html#id2727661 [Configuring virtual machines]
:http://www.virtualbox.org/manual/ch03.html#id321700 [USB Support]
:[http://www.virtualbox.org/manual/ Oracle VM VirtualBox online Manual]
:[http://download.virtualbox.org/virtualbox/UserManual.pdf UserManual.pdf]

====Extension Pack====
:[http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html Oracle VM VirtualBox Extension Pack] '''Personal Use License'''
::All Platforms (Windows, Mac OS X, Solaris and Linux)
* '''Personal Use Licensed not OSE'''

==='''[[VMware]] Player'''===
[https://www.vmware.com/tryvmware/?p=player&lp=default Download VMware Player (free)]

* VMware Player appliance of soas-v3-Mirabelle
:Compressed in .zip file
:[http://people.sugarlabs.org/Tgillard/Soas-v3-Mirabelle.zip Download]
::This appliance is ready to run "firstboot" (agree/user name/password/tz/etc)
::'''sugarroot''' is the root password.

* VMware Player appliance Trisquel-3 (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel3.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Trisquel-4+sugar (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel-4-sugar-VMPlayer.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Sugar on a Stick v2 (Blueberry)
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.txt Read this first.]
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.tar.gz download]

* VMware Player appliance of openSUSE-Sugar
:[[VMware#openSUSE |Read this first.]]
:[http://sourceforge.net/projects/opensuse-edu/files/Sugar/openSUSE-Sugar-vmware-vmx.tar.bz2/download download]
:[[Talk:VMware#change_networking|networking help]]
:[http://old-en.opensuse.org/How_to_use_downloaded_SUSE_Studio_appliances how to use]

===Older Virtual Appliances===

'''Hint for the following Appliances: when Downloading xxxx.mf and xxxx.ovf files use "save as" to download then hit < on browser to return to previous screen in browser'''

*'''Sugar on a Stick v2 Bluberry'''
:link: [[Sugar on a Stick/Blueberry|Blueberry]] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry_ovf_README_FIRST.txt Read this first.]
:'''download and import 3 files''': [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.ovf soas-2-blueberry.ovf] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.mf soas-2-blueberry.mf] [http://people.sugarlabs.org/Tgillard/soas-2-blueberry.vmdk soas-2-blueberry.vmdk]

*'''Sugar on a Stick v1 Strawberry'''
:Link: [[Sugar on a Stick/Strawberry|Strawberry]]
: [http://www.sugarlabs.org/static/soas/soas-strawberry-vdi.zip soas-strawberry-vdi.zip] Sugar 0.84 (22 June 2009)
::This is a compressed VirtualBox Hardisk. Decompress it and Create a new VirtualBox Appliance that points to this '''existing .vdi Hard Disk''' not a new one.
::'''[http://wiki.sugarlabs.org/go/Talk:Emulator_image_files#How_to_Update_Soas-v1-Strawberry-vdi How_to_Update_Soas-v1-Strawberry-vdi Activities]'''

*'''openSUSE-Sugar-11.3'''
: Reference links: [http://download.opensuse.org/repositories/Education/images/iso/openSUSE-Sugar-11.3.i686-1.0.0-Build6.3.iso openSUSE-Sugar-11.3.i686-1.0.0-Build6.3.iso] Uploaded 26 September 2010 
:'''download and import 3 files''':openSUSE_sugar.ovf [http://people.sugarlabs.org/Tgillard/openSUSE_sugar.ovf openSUSE_sugar.ovf] [http://people.sugarlabs.org/Tgillard/openSUSE_sugar.mf openSUSE_sugar.mf] [http://people.sugarlabs.org/Tgillard/openSUSE-Sugar-11.3.vmdk openSUSE-Sugar-11.3.vmdk]
::8-GB VirtualBox hard disc
::English and English keyboard
::USA-Los Angeles (Pacific timezone)
::Autologin- user=sugar password=sugaruser
:::Ready to auto-configure to your hardware on first booting.
:::'''note choose /dev/sda2 when prompted to do so on first run'''

*'''U'''buntu'''S'''ugar'''''R'''emix''
: Reference links: [[Community/Distributions/Ubuntu]], https://wiki.ubuntu.com/Sugar
::''shutdown does nothing from sugar; To exit sugar use "Log Out" then shutdown from bottom right gdm bar''

:'''download and import 3 files''': [http://people.sugarlabs.org/Tgillard/USR-922-IRC-Remix.ovf USR-922-IRC-Remix.ovf] [http://people.sugarlabs.org/Tgillard/USR-922-IRC-Remix.mf USR-922-IRC-Remix.mf] [http://people.sugarlabs.org/Tgillard/USR-i386-20100922.vmdk USR-i386-20100922.vmdk]
::TZ=LA USA USA Keyboard 8-GB HD fully updated on 22 September 2010 with
::apt-get Updates
::apt-get Upgrade
::Remixed to add
:::Surf-115.xo browser
:::IRC.xo -(edited to log in to #sugar and #ubuntu-sugarteam)
:::Analyze.xo
:::'''Import the 3 files into Oracle VirtualBox'''
::: User=sugar autologin
::: Password=sugaruser
*'''install the VirtualBox guest additions'''
::Integrates a Running VirtualBox Appliance with the desktop
:install the VirtualBox guest additions with ''sudo apt-get install virtualbox-ose-guest-utils''
==='''[[QEMU]]'''===
:[[Sugar_Creation_Kit#QEMU_Virtualization|instructions, downloads]]

== Image installation tools ==
==='''[[Sugar_on_a_Stick/ZyX-LiveInstaller|ZyX-LiveInstaller]]'''===
* ZyX-LiveInstaller allows you to install Sugar from either a booted Live USB device,
* or Live CD media to a system or external disk.
* It creates an exact copy of your running live CD as a traditional (Persistent) installation on your hard-disk (or removable media such as SD or USB storage devices.
: This program can be useful for installing to a virtualized hard disk. It is not included in builds after soas-v2 Blueberry, so it must be downloaded and installed to use.
: In a running SoaS Terminal session or console, execute the following commands:
: {{Code|su}}
: {{Code|yum install zyx-liveinstaller gparted}}

===[http://www.easyvmx.com EasyVMX!]===
:'''Make a VirtualBox or VMware Player appliance with a burned CD of your favorite xxx.iso'''

* '''http://www.easyvmx.com/ is a web site that builds a vmx file to your specifications (free).'''

: Works fine, runs on most platforms, and has persistence after installation. (tested with Trisquel 4.0.1 DVD 12/24/2010 satellit)
:: Virtual Appliance that you create Can be opened with either VirtualBox or VMware Player
: VirtualBox 4.0 Download (free): http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html
: VMware Player download (free): http://www.vmware.com/tryvmware/
:::(Note:VMware Workstation not needed for VMware Player to create Virtual Appliance)

::specified a 8 GB Hard Drive; name; and other parameters
::downloaded, in browse, the Custom vmx file as a .zip file
::Decompressed the .zip file

: Insert the CD of your favorite xxx.iso

::Open VirtualBox4.0 or VMware Player and point it to this vmx file
:::In VirtualBox Settings/specify CD Player (/dev/sr0); Start
:::VMware Player starts CD automatically

* EXAMPLE: soas-i386-20100926.17.iso burned to a CD
::Put soas-i386-20100926.17 CD in your CD Drive
::CD boots in VirtualBox-4.0 or VMware Player application
::Sugar Starts

*To install to EasyVMX Hard Disk:
:Open Sugar-terminal:
su
liveinst
Anaconda installer opens
Initialize all disks
Install procedes normally
reboot
firstboot
Log in to user you specified

'''HINT: copy all of the EasyVMX Hard Disk Files on a 2 GB USB stick.'''
::'''(note runs about 10x slower on a USB stick)'''
::Example above created a 1.4 GB set of files'
:Copy-Paste all files
: Sugar on a Stick in VirtualBox or VMware Player Hard Disk format with persistence
::Portable (Student can take home and run on home Computer)
::Run it on different Platforms

==Click for: [[Talk:Emulator image files|More Discussions]]==

==References==
* [[Mac OS X-Boot USB with VirtualBox]]
* [http://lists.laptop.org/pipermail/devel/2008-September/019643.html Tom van Overbeek describes how to run Sugar using QEMU]
* [https://fedoraproject.org/wiki/Features/BoxGrinder BoxGrinder: a set of tools used for building appliances (virtual machines)]
* [http://fedoraproject.org/wiki/Licensing Licensing-License types and info for exported Appliances-]

== Thanks ==

Thanks for this work satellit_, emulators are a great way to develop and test stuff. --[[User:RafaelOrtiz|RafaelOrtiz]] 17:19, 13 April 2011 (EDT)

Sugar Creation Kit

2011-05-15T17:55:07Z

Bert: /* Etoys-116 Soasv5 RC3 Error Fix */ formatting

<noinclude>
[[Category:Live USB]]
</noinclude>

==Sugar Creation Kit DVD==
[[File:Sugar Creation Kit.png]]
[[File:Download Mirabell.png|left|link=http://download.sugarlabs.org/images/SugarCreationKit-123.iso]]

:'''Caution, this is a large file, at 3.8 GB'''

:A complete DVD containing all the resources required to create all 3 versions of Sugar-on-a-Stick without requiring Internet access.

*[http://download.sugarlabs.org/images/SugarCreationKit-123.md5 SugarCreationKit-123.md5]
*[http://download.sugarlabs.org/images/SugarCreationKit1.2.3-Contents.txt List of Contents]

Uses:
*"sneakernet" or behind firewall at school.
*save bandwidth on servers.
*download once and distribute copies locally.

=='''[http://www.sugarlabs.org/ Sugar]'''==
;Click this^ link
:http://www.sugarlabs.org/
* Main sugarlabs introductory page

=== '''[[Downloads | Get Sugar ]]''' ===
;Click this^ link
* Main Page to Download Sugar

==[http://chat.sugarlabs.org:9090/?channels=sugar Chat login with list of Channels and languages]==
;Click this^ link to enter chat

* '''[http://webchat.freenode.net/?randomnick=1&channels=sugar&prompt=1 Join Sugar chat room for Help in English]''' (with translations to Spanish on #sugar-es)
*'''[http://webchat.freenode.net/?randomnick=1&channels=sugar-es&prompt=1 Sugar chat room in Español]''' (con traducción al Inglés de #sugar)
Pida ayuda a través de este canal #sugar-es Por favor, sea cortés y hacer sus preguntas.
Los voluntarios no pueden estar en línea todo el tiempo.
Sea paciente y permanecer conectado durante varios minutos para ver su respuest
:::(utilizar la función de meeting para la traducción de estos artículos)
* Ask for help on these IRC channels by clicking on either of the above links (English or Spanish)

* '''NOTE: there are 4 channels on IRC: #sugar; #sugar-es; #sugar-it; #sugar-de'''
::these channels which use MEETING to do translations between them.
::to join enter this in command line of IRC: '''/join #sugar-it''' ; '''/join #sugar-de'''

::<big><big>Please be courteous and ask your questions.</big></big>
::<big><big> Volunteers may not be on line all of the time. Be patient and stay connected for several minutes to see their answer.</big></big>
:<big><big>'''Read the [[Sugar_Creation_Kit#Floss_Manuals| Floss Manuals]] first!'''</big></big>
:: Most answers can be found in them

*More about [http://wiki.sugarlabs.org/go/Internet_Relay_Chat Internet_Relay_Chat]

==='''[[Sugar_Labs/Communication_channels|Communication channels]]'''===
;Click this ^ link to access a page with all the means to communicate with Sugar Labs contributors and learners. It includes mailing lists, chat rooms, blogs, forums, Jabber networks, video, mail and telephone contacts.
====World Time Converter====
*http://www.timeanddate.com/worldclock/converter.html

====Tiny URL====
*http://ietherpad.com/

== '''ON-LINE VERSION''' ==

:'''An expanded and enhanced listing of Items Included in the SugarCreationKit DVD ver 1.2.3 (see Above)'''

::'''NOTE: There are newer and additional items on this web page that are not in the SCK DVD.iso'''

<big><big>''Use to Download the elements you need and burn to your own DVD to save Downloading all of the above SCK DVD.iso''</big></big>

: Look below to the [[#References|References section]] to see how to then convert your customized DVD to an .iso

====Introduction to '''[[Sugar on a Stick]]'''====
:::'''Read this first ^'''

Cautions with using Live USB's.pdf

*[[Sugar on a Stick/Installation/Variations#Cautions with using Live USB devices]]

How to Make a live USB.pdf:
*(instructions on how to make a live USB in Windows, GNU/Linux, and Intel Mac's) [[Sugar on a Stick/Installation#with Microsoft Windows]]
*WINDOWS: [[Sugar on a Stick/Windows]]

====[[File:SugaronastickMirabelle.png|240px]] How to use Sugar on a Stick (SoaS)====

# [[Downloads|Download]]
# [[Sugar_on_a_Stick/Installation|Install]]
# [[Sugar_on_a_Stick/Boot|Boot]]
# [[Sugar_on_a_Stick/Usage|Use]]

<big>Burn a SoaS.iso to a CD and Boot with the resulting CD</big>

=====[[File:SugaronastickMirabelle.png|120px]][http://wiki.sugarlabs.org/go/Community/Distributions/Fedora-SoaS Tests of Nightly Composes]=====
::Click link to open ^
:http://wiki.sugarlabs.org/go/Community/Distributions/Fedora-SoaS
:http://alt.fedoraproject.org/pub/alt/nightly-composes/current.html

=====[[File:XO_buddy.png|40px]][http://wiki.sugarlabs.org/go/Community/Distributions/Fedora-SoaS#SoaSv5-20110415-i6865 SoaS v5-20110415 Beta]=====
:http://wiki.sugarlabs.org/go/Community/Distributions/Fedora-SoaS#SoaSv5-20110415-i686 Note actually x86-64
;::'''Beta Version for testing only'''

=====[[File:XO_buddy.png|40px]][[Sugar_on_a_Stick/Mango_Lassi|SoaS v4 Mango Lassi]]=====
:click link ^ for details

: '''(The current version of Sugar on a Stick)'''
*'''[http://alt.fedoraproject.org/pub/alt/spins/linux/releases/14/Spins/i686/Fedora-14-i686-Live-SoaS.iso download Mango Lassi]''' (32-bit build)
*'''[http://alt.fedoraproject.org/pub/alt/spins/linux/releases/14/Spins/x86_64/Fedora-14-x86_64-Live-SoaS.iso download Mango Lassi]''' (64-bit build)
: (Burn the .iso to a CD and Boot with the resulting CD)

*'''Activities Compatible with Mango Lassi & Mirabelle
:'''Editable Listing of Activity Compatibility''' [[Features/Soas_V4/ASLOxo Activity Test Table]] '''Please Use this wiki page to report your findings'''

=====[[File:XO_buddy.png|40px]][http://download.sugarlabs.org/soas/releases/soas-3-mirabelle.iso SoaS v3 Mirabelle]=====
:Click link ^ to download

=====[[File:XO_buddy.png|40px]][http://download.sugarlabs.org/soas/releases/soas-2-blueberry.iso SoaS v2 Bluberry]=====
::Click link ^ to download

====Spins Archives====
*'''[http://download.sugarlabs.org/soas/releases/ Sugarlabs Archive to download Mirabelle and earlier SoaS versions]'''
*'''[http://alt.fedoraproject.org/pub/alt/spins/linux/releases/13/Spins/ Fedora 13 Spins Archive]'''
*'''[http://alt.fedoraproject.org/pub/alt/spins/linux/releases/14/Spins/ Fedora 14 Spins Archive]'''
: (Burn the .iso to a CD and Boot with the resulting CD)
*'''[[Talk:Sugar_on_a_Stick_release_process#Test_Matix|Testing of nightly spins]]'''

====Hardware Compatibility====
:EeePC: http://fedoraproject.org/wiki/EeePc
:[http://www.mydigitallife.info/2008/07/06/comprehensive-list-of-how-key-to-press-to-access-bios-for-various-oem-and-computer-systems/ key-to-press-to-access-bios-for-various-oem-and-computer-systems]

:smolt profiles:http://www.smolts.org/
::http://smolts.org/smolt-wiki/Main_Page#Usage

====[[Sugar_Creation_Kit/Sck/SoaS_installation_variations|SoaS Installation variations]]====
:Click Link ^
: A collection of install methods

====[[:Category:Live USB]]====
:click link ^
:A collection of links on how Live USB's are used in different distributions
=====Commercial Source of Live SoaS Sticks=====
*http://on-disk.com/product_info.php/cPath/28_310/products_id/908#!tab6
=====WiFi=====
:Wifi (Open FirmWare for WiFi networks): http://www.ing.unibs.it/~openfwwf/
::http://www.ing.unibs.it/openfwwf/
:http://www.h-node.com/wifi/view/en/2/BCM4311--rev-02-/1/1/Broadcom/undef/undef/undef/undef
:http://linuxwireless.org/en/users/Drivers/b43#Known_PCI_devices

===='''[[Community/Distributions| Community Distributions]]'''====
: click this link^for complete listing
:'''Linux distributions where sugar is used:'''
:[[Image:Fedora-small.jpg|link=Community/Distributions/Fedora]][[Community/Distributions/Fedora|Fedora]] F13 SoaS, F14 SoaS, f15-gnome3-shell and sugar0.92.0 How to install Sugar packages
:[[File:Trisquel_icon.png|link=Community/Distributions/Trisquel]][[Community/Distributions/Trisquel|Trisquel]] Tris 4.0 (Ubuntu 10.04LTS); Tris 4.5 (Ubuntu 10.10); Sugar sweets 0.88.1 or 0.90.1
:[[Image:Mandriva-small.png|link=Community/Distributions/Mandriva]][[Community/Distributions/Mandriva|Mandriva]] 2010.2 Mandriva Sugar 0.88.0
:[[Image:Debian-small.jpg|link=Community/Distributions/Debian]][[Community/Distributions/Debian|Debian]] Debian 6 Sugar 0.88.1
:[[File:LMD-small.png|link=Community/Distributions/Linux_Mint_Debian]][[Community/Distributions/Linux_Mint_Debian|Linux Mint Debian]] Debian 6 Sugar 0.88.1
:[[Image:Caixa_M%C3%A1gica-small.jpg|link=Community/Distributions/Magalhães]][[Community/Distributions/Magalhães|Caixa Mágica]] based on Mandriva 2010.1 repositories Sugar 0.88.0
:[[Image:Ubuntu-small.jpg|link=Community/Distributions/Ubuntu]][[Community/Distributions/Ubuntu|Ubuntu]] Sugar sweets 0.88.1 or 0.90.1
:[[Image:Suse-small.jpg|link=Community/Distributions/OpenSUSE]][[Community/Distributions/OpenSUSE| openSUSE]]
:[[Image:Tuquito.png|link=Community/Distributions/tuquito]][http://wiki.sugarlabs.org/go/Community/Distributions/tuquito tuquito] NEW Community Distribution based on Ubuntu 10.10

*'''[http://download.sugarlabs.org/soas/releases/ Sugar Labs Archive to download Mirabelle and earlier SoaS versions]'''
*'''[http://alt.fedoraproject.org/pub/alt/spins/linux/releases/13/Spins/ Fedora Spins Archive]'''

=====[[File:Gnome_icon.png]][http://wiki.sugarlabs.org/go/Community/Distributions/Fedora#Fedora_15_gnome3_with_sugar_0.92.0 Fedora 15 gnome3 with sugar 0.92.0]=====
:click this ^ link
{{Admon/note|Note:|This is an Beta Version-for testing sugar and sugar-emulator in the next version of Fedora 15. It can be Updated to gnome3-shell 3.0.1 }}

====[http://download.sugarlabs.org/ Index of Sugar Labs Archive]====
*click above link ^

====[[Sck/ASLOxo|ASLOxo-5.iso]]====
*click above link ^
*(275.xo files and worldmap.pdf files)
:'''New: Updated activities through 02/08/2011'''
*[http://download.sugarlabs.org/images/ASLOxo-5.iso ASLOxo-5.iso] 1.3 GB (DVD)
*[http://download.sugarlabs.org/images/Contents_of_ASLOxo-5-iso.txt View: Contents_of_ASLOxo-5-iso.txt] 8.5K

* These can be copied to a 2-GB USB device and drag-dropped into the Sugar Journal to install them.

====[[Sck/activities|Activities]]====
*click above link ^
*'''listing: [[Activities]]''' Descriptions and Developer Pages
* OLPC listings: '''[http://wiki.laptop.org/index.php?title=Category:Activities Activities]'''
* OLPC AU: [http://wiki.laptop.org/go/Activities/OLPCAU/10.1.3 Activities_OLPCAU_10.1.3]
* '''[http://wiki.laptop.org/go/Recursos_en_espanol Recursos_en_espanol] '''Los siguientes recursos han sido creados por personal de distintos deployments de America Latina y otros colaboradores.
======Etoys-116 Soasv5 RC3 Error Fix======
presence-service is obsolete, but etoys still uses it and nothing else. No idea why it no longer runs.
Because PS does not find the buddy icon file. If I do
'''touch ~/.sugar/default/buddy-icon.jpg'''
then Etoys starts fine. - Bert -

=====logo=====
*http://logoworks.wikispaces.com/
=====surf browser=====
: alternate to sugar-browse
; Included in latest f15 sugar 0.92.1 as the main web browser
:: Works in situations where sugar-browse will not start
* Download: http://people.sugarlabs.org/Tgillard/Surf-115.xo
* RPM: http://koji.fedoraproject.org/koji/getfile?taskID=3008630&name=sugar-surf-115-1.fc16.noarch.rpm
* git: http://git.sugarlabs.org/surf

=====Turtle art 107-1 rpm=====
*http://kojipkgs.fedoraproject.org/packages/sugar-turtleart/107/1.fc15/noarch/sugar-turtleart-107-1.fc15.noarch.rpm
: for f15
; Included in latest f15 sugar 0.92.1
*http://koji.fedoraproject.org/koji/buildinfo?buildID=239454

====DVD covers; artwork & screenshots====
* sugarlabs_SoaS-Creation-Kit_avery_cd_label_2up.pdf http://people.sugarlabs.org/Tgillard/sugarlabs_SoaS-Creation-Kit_avery_cd_label_2up_Mirabelle.pdf
* sugarlabs_Sugar-demo_avery_cd_label_2up.pdf http://people.sugarlabs.org/Tgillard/sugarlabs_Sugar-demo_avery_cd_label_2up_Mirabelle.pdf
* Flyer_englisch.pdf *http://people.sugarlabs.org/Tgillard/Flyer_englisch.pdf (Poster-Sugar Learning Program; 2-sided with text from past Show)
* Booth_Banners http://wiki.sugarlabs.org/go/Marketing_Team/Booth_Banners
* LinuxTag http://www.flickr.com/photos/39656470@N02/sets/72157620524327203/ SeanDaly
* Screen Shots http://wiki.sugarlabs.org/go/Marketing_Team/Screen_Shots
* http://wiki.sugarlabs.org/go/Marketing_Team/T-Shirt nice collection of images
* Fedora 15 Gnome3-shell with sugar-emulator: http://wiki.sugarlabs.org/go/Community/Distributions/Fedora#GnomeShell

====[[File:Sugarlabs_mainpage_07.png|link=http://en.flossmanuals.net/]]'''[http://en.flossmanuals.net/ Floss Manuals]'''====
:;Click this link ^
(Important Manuals on how to use Sugar Applications and Features)
:'''READ THESE FIRST!'''

*'''[http://people.sugarlabs.org/Tgillard/floss_manuals/ Sugarlabs Download Page]'''
::(Local ARCHIVE of the.pdf files shown below:)

:* Source Links:

:: Introduction to Sugar http://en.flossmanuals.net/sugar
:::'''[http://www.archive.org/details/MakeYourOwnSugarActivities MakeYourOwnSugarActivities] Internet Archive''' Publishing Quality
:::: In PDF, EPUB, Kindle, Daisy, Full Text. DjVu formats
:::[http://people.sugarlabs.org/Tgillard/floss_manuals/ActivitiesGuideSugares-es-2011.01.21-18.28.05.pdf MakeYourOwnSugarActivities-es] with corrected index
:::What is Sugar http://people.sugarlabs.org/Tgillard/floss_manuals/What_is_Sugar_28Oct08.pdf
:::Browse http://people.sugarlabs.org/Tgillard/floss_manuals/Browse_06Sep08.pdf
:::Chat http://people.sugarlabs.org/Tgillard/floss_manuals/Chat_09Sep08.pdf
:::Collaboration http://people.sugarlabs.org/Tgillard/floss_manuals/Collaboration_31Jan10.pdf
:::SugarCollaboration http://en.flossmanuals.net/ActivitiesGuideSugar/SugarCollaboration
:::FunWithTheJournal http://people.sugarlabs.org/Tgillard/floss_manuals/Fun_with_the_journal_09Nov10.pdf
:::Linux Command Line http://people.sugarlabs.org/Tgillard/floss_manuals/Linux-command-line_16Apr09.pdf
:::ActivitiesGuideSugar-English http://people.sugarlabs.org/Tgillard/floss_manuals/Activitys_Guide-sugar_en_09Nov10.pdf
:::Record http://people.sugarlabs.org/Tgillard/floss_manuals/Record_06Sep08.pdf
:::The Terminal http://people.sugarlabs.org/Tgillard/floss_manuals/Terminal_06Sep08.pdf
:::Turtle Art http://people.sugarlabs.org/Tgillard/floss_manuals/TurtleArt_06Sep08.pdf
:::Write http://people.sugarlabs.org/Tgillard/floss_manuals/Write_27Sep08.pdf
:::Reading_and_sugar: http://people.sugarlabs.org/Tgillard/floss_manuals/Reading_and_sugar_28Sep10.pdf
:::Text to Speech: http://people.sugarlabs.org/Tgillard/floss_manuals/Text_and_Speak_09Nov10.pdf

====Booki====
*[http://book.treehouse.su/ Sugarlabs Booki]
:click this link ^
; (This is a site under construction)
Edward Cherlin wrote:
[IAEP] Fwd: New booki for replacing textbooks with OER 04/01/2011

Please take a look at

http://booki.flossmanuals.net/

a site for collaborative authoring and publishing of manuals for Open
Source software. Sugar Labs has set up another trial instance of the
same booki software for OER development. I am arranging for some
further administrative changes so that we can begin to use it, and
will then invite various interested persons and groups to try it out
and to discuss what we might be able to do by combining this with
Sugar and other education software.

:[http://www.crowdrise.com/Replacetextbooks/ Replacetextbooks]
:[http://www.booki.cc/booki-user-guide/ Booki User Guide]
:[http://support.booki.cc/ Support]
:[http://blog.booki.cc/ Blog]
:[http://book.treehouse.su/meta/_v/1.0/importing-a-book/ Booki importing-a-book]
:http://booki.flossmanuals.net/ FLOSS Manuals WRITE
::http://booki.flossmanuals.net/xo Depreciated
====[http://mapmeld.appspot.com/khan_categories.html Khan Academy videos in OGV format]====
:click this link ^
:Re: [IAEP] Khan academy content 04/05/2011
You can download around 1000 of the Khan Academy videos in OGV format
(playable on XO laptops) from Archive.org Here's an English/Spanish
index of relevant categories
If you're skeptical or haven't seen his videos, his talk sparked a great
discussion about math education on Hacker News:
http://news.ycombinator.com/item?id=2307532

For more recent videos, including YouTube, there's this media guide:
http://wiki.laptop.org/go/MediaGuide

Regards,
Nick Doiron
*link:http://www.khanacademy.org/

=====Flash Player=====
: needed for firefox viewing of Khan academy lectures
*http://plugindoc.mozdev.org/linux.html#Flash

====References====

* '''How to make your own custom Sugar-Creation_Kit.iso file''' (How this DVD was converted to an .iso file)
*# Collect, annotate and sort the files you want in a folder on your Desktop.
*# Burn the contents of this folder to a CD or DVD.
*# Use the following command in Terminal as the root user:
*#: <big><code>dd if=/dev/sr0 of=Sugar-Creation-Kit.iso</code></big>
*: Sample output:
<ul><ul><ul>
<pre>
dd if=/dev/sr0 of=Sugar-Creation-Kit.iso
5555584+0 records in
5555584+0 records out
2844459008 bytes (2.8 GB) copied, 232.86 s, 12.2 MB/s
</pre></ul></ul></ul>
*the resulting .iso file can be sent over the internet or used to make copies by burning to a DVD

* '''How To Sugarize a Program'''
:Instructions on how to make a program appear in the (F3) Home view of Sugar as an icon
:: http://people.sugarlabs.org/Tgillard/sugarize/wiki-sugarize.txt
:: [[Running Linux Applications Under Sugar]]
===='''[[The Undiscoverable]]'''====
:click this link ^ for more details and examples
: (The Undiscoverable Features of Sugar)
: Features and tips not easily discovered about using Sugar
=====HTMLDOC=====
*http://www.htmldoc.org/documentation.php/Introduction.html
HTMLDOC software, version 1.8.27. HTMLDOC converts Hyper-Text Markup Language ("HTML") input files
into indexed HTML, Adobe® PostScript®, or Adobe Portable Document Format ("PDF") files.

====E-books====

* [[Education Team/Creating textbooks]]
*Reading And Leading With One Laptop Per Child http://en.flossmanuals.net/ReadingandSugar/Introduction

====Graphic installers====
=====[http://wiki.sugarlabs.org/go/Sugar_Creation_Kit/Sck/Liveusb-creator Liveusb Creator]=====
:Click link above ^ for details
::Fedora and Windows (BEST METHOD TO USE)

* how to create and use liveusb-creator [[fedora:FedoraLiveCD/USBHowTo]] [[fedora:How to create and use Live USB#Graphical Method - Windows or Fedora]]
* Liveusb-creator https://fedorahosted.org/liveusb-creator/
* F14 version for windows released: http://lewk.org/blog/liveusb-creator-3.9.3.html 01/06/2011

=====ZyX-LiveInstaller=====
* [[Sugar on a Stick/ZyX-LiveInstaller]]
: http://en.wikipedia.org/wiki/Loopback_disk_device

=====UNetbootin=====
* [http://unetbootin.sourceforge.net/unetbootin-windows-latest.exe unetbootinwindows471.exe for windows]
* [http://unetbootin.sourceforge.net/unetbootin-linux-latest unetbootinlinux471]
* [http://unetbootin.sourceforge.net/ UNetbootin]
* (Advanced) [http://sourceforge.net/apps/trac/unetbootin/wiki/commands UNetbootin Command line]
* [[Community/Distributions/Linux_Mint_Debian#How_to_Make_a_2GB_Installer_USB|How to Make a 2GB Installer USB with UNetbootin]]

=====pendrivelinux=====
*[http://www.pendrivelinux.com/category/usb-installs-from-linux/ usb-installs-from-linux] How to Do it Information
*[http://www.pendrivelinux.com/universal-usb-installer-easy-as-1-2-3/ universal-usb-installer-easy-as-1-2-3] Windows
*[http://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/ boot-multiple-iso-from-usb-via-grub2-using-linux] linux (Advanced)
*[http://www.pendrivelinux.com/boot-a-usb-flash-drive-in-virtualbox/#more-3606 boot-a-usb-flash-drive-in-virtualbox] VirtualBox
=====openSUSE Live USB stick=====
*[http://en.opensuse.org/Live_USB_stick openSUSE Live USB stick]
*[http://software.opensuse.org/113/en Downloads]
====[http://wiki.sugarlabs.org/go/Sugar_Creation_Kit/Sck/Expert_install_methods Expert install methods]====
:click this link ^ for more details and examples
* [[Talk:Sugar on a Stick/Blueberry#liveinst command to install to Hard-Disk.2FUSB from Soas CD|How to install to a 4GB USB using liveinst (ANACONDA) from SoaS]]

* Use livecd-iso-to-disk script to write a live USB [[Sugar on a Stick/Linux]], [[Fedora:How to create and use Live USB#Graphical Method - Windows or Fedora|Fedora page]]
*:[[fedora:Livecd-iso-to-disk.pod|Technical Details]]

* zyxliveinstaller Instructions [[Sugar on a Stick/ZyX-LiveInstaller]]
* Download: zyxliveinstaller0.2.4-1.noarch.rpm http://people.sugarlabs.org/Tgillard/zyx-liveinstaller-0.2.4-1.noarch.rpm
=====<big>[[Sugar_Creation_Kit/sck/dd_installs|Use "dd" command]]</big> =====
:click this link ^ for more details and examples. For ADVANCED USERS ONLY.
: '''to make an install USB from a liveCD .iso file'''
*Also see: [[Sugar_on_a_Stick/Linux/openSUSE|openSUSE dd to USB with persistence]]
*Great for netbooks
:Use (live).iso and terminal to make bootable USB
::Use to install to HD or USB without needing a DVD/CD ROM

=====[http://wiki.sugarlabs.org/go/Sugar_Creation_Kit/sck/Building_a_bootable_Mac_USB Building a bootable Mac USB]=====
:Click above Link ^
:: (tested on a MacBook Air)

=====Boot Helper CD's=====
*MAC SoaS-3 Mirabelle Boot DISK
::[http://people.sugarlabs.org/Tgillard/soas-3-boot-test.iso soas-3-boot-test.iso] (Burn this to a CD and boot with it)
::[http://people.sugarlabs.org/Tgillard/soas-3-boot-test.txt Read Me First & Credits to Programmer]
*MAC SoaS-4 Mango Lassi Boot DISK
::[http://www.wronkiewicz.net/soas-4-boot-test.iso soas-4-boot-test] (Burn this to a CD and boot with it)
*rEFIt
::[http://refit.sourceforge.net/doc/ rEFIt]
::[http://refit.sourceforge.net/doc/c1s5_burning.html burn a bootable rEFIt CD on Mac OS X] Used to Boot live USB's in a Mac
rEFIt is a boot menu and maintenance toolkit for EFI-based machines like the Intel Macs.
You can use it to boot multiple operating systems easily, including triple-boot setups with Boot Camp.
It also provides an easy way to enter and explore the EFI pre-boot environment.

====Backup and Restore====
* Backup (Activity) http://activities.sugarlabs.org/en-US/sugar/addon/4326
* Restore (Activity) http://activities.sugarlabs.org/en-US/sugar/addon/4327

* Mirabelle backup (deja-dup) [[Sugar on a Stick/deja-dup]]

===='''[[QEMU|QEMU Virtualization]]'''====
:click this link ^ for more details and examples

:In Gnome terminal:
su
yum install @virtualization

::Start (Graphical): Applications/System Tools/Virtual Machine Manager

*installs soas.iso files to VM HD (with liveinst command in terminal of running Virtual Machine)

====BoxGrinder====
*http://boxgrinder.org
*http://boxgrinder.org/tutorials/
:BoxGrinder creates appliances (also called images) from simple plain text Appliance Definition files.
*http://boxgrinder.org/tutorials/boxgrinder-build-meta-appliance/
*http://boxgrinder.org/download/boxgrinder-build-meta-appliance/

===='''[[VMware]] Player Virtualization'''====
:click this link ^ for more details and examples
[https://www.vmware.com/tryvmware/?p=player&lp=default Download VMware Player (free)]

====VMware Player Appliances====
* VMware Player appliance of SoaS-v3-Mirabelle
:Compressed in .zip file
:[http://people.sugarlabs.org/Tgillard/Soas-v3-Mirabelle.zip Download]
::This appliance is ready to run "firstboot" (agree/user name/password/tz/etc)
::'''sugarroot''' is the root password.

* VMware Player appliance Trisquel-3 (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel3.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Trisquel-4+sugar (NEW) 01/05/2011
:Compressed in .zip file
:[http://download.sugarlabs.org/images/vmplayer/Trisquel-4-sugar-VMPlayer.zip download]
::User=sugar
::Password=sugaruser

* VMware Player appliance Sugar on a Stick v2 (Blueberry)
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.txt Read this first.]
:[http://people.sugarlabs.org/Tgillard/Blueberry-vmx.tar.gz download]

* VMware Player appliance of openSUSE-Sugar
:[[VMware#openSUSE |Read this first.]]
:[http://sourceforge.net/projects/opensuse-edu/files/Sugar/openSUSE-Sugar-vmware-vmx.tar.bz2/download download]
:[[Talk:VMware#change_networking|networking help]]
:[http://old-en.opensuse.org/How_to_use_downloaded_SUSE_Studio_appliances how to use]

===='''[[VirtualBox|VirtualBox Virtualization]]'''====
:click this link ^ for more details and examples
With [[wikipedia:VirtualBox|VirtualBox®]] one can run Sugar in a window on Microsoft Windows, Intel-based Apple Macintosh, or Linux host computers from a virtual machine (VM) window. [http://www.oracle.com/technetwork/server-storage/virtualbox/overview/index.html VirtualBox overview]
* [[VirtualBox]]
* A good solution for Macintosh computers

*[http://www.virtualbox.org/wiki/Downloads VirtualBox downloads] Windows/Linux/Intel Macs
*[http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html Oracle VirtualBox downloads] (alternate link)
*[http://www.virtualbox.org/manual/ch02.html#id352318 Installing on Linux hosts] Read this if VirtualBox does not install.
*[http://forums.virtualbox.org/viewforum.php?f=8 VirtualBox on Mac OS X Hosts]
=====[http://people.sugarlabs.org/Tgillard/Trisquel41_sugar_installer.iso '''Trisquel41_sugar_installer.iso''']=====
*click above link '''^''' to download (1.1GB)
*'''This DVD.iso is a great way to "SneakerNet" distribute this VM Appliance'''
:Revised 03/02/2011 to remove sugar identity
:'''RECOMMENDED'''
*Contents of DVD:
: Instructions and .vmdk/.ovf files to import
32bit-VirtualBox Installers (OSE) (Directory with install files for VirtualBox 4.0.4)
(Does not include Free for Personal Use licensed extension pack) - includes instructions on how to download for personal use.
ReadMeFirst_Install_Instructions.pdf (Instructions-how to install VirtualBox and import appliance)
trisquel-sugar-4.1-i686-feb18.ovf
trisquel-sugar-4.1-i686-feb18-disk1.vmdk
UserManual.pdf (VirtualBox 4.0.4 User Manual-269 pages)

* Cleared of Sugar Learner identity. Starts on color selection screen (Click the <===(back) button to change the Learner name.)

{{Admon/note|
* '''When making a new VM''', to clear the Sugar Journal of old entries and to avoid identity conflicts among copies of the VM, enter the command {{Code|rm ~ rf /.sugar}} in the Terminal activity. Then shutdown the VM. This will clear all Learner information on the VM and let you start with a fresh install. Skipping this will result in collisions in the Neighborhood view of the Jabber network between separate copies of the appliance. Verify the presence of the '''.sugar''' directory by entering {{Code|ls -a}} in Terminal.
* '''When cloning a customized VM''', in order to keep the Journal and installed .xo Activities, use {{Code|rm ~/.sugar/default/owner.key*}} in the Sugar Terminal, and then shutdown the VM. This leaves the Journal entries and removes only the previous Learner's identity key files.}}

[[File:VirtualBox.png|75px|link=Emulator image files]]

===='''[[Emulator_image_files|All Prebuilt VirtualBox Appliances]]'''====
: click this link ^ to see a complete list of available VirtualBox Appliances
::Try the appliances listed below first.
::they are listed with the Recommended version first and older ones below.

====[[File:Trisquel_icon.png]][http://wiki.sugarlabs.org/go/Emulator_image_files/Trisquel#Trisquel-4.1-sugar Trisquel-4.1-sugar]====

:(click this ^ link for details)
:'''RECOMMENDED'''
* Sugar Desktop ONLY
: Ubuntu 10.04 LTS with Sugar sweets 0.88.1

*:[[Community/Distributions/Trisquel]]

* download and import 2 files:
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned-disk1.vmdk
*# http://people.sugarlabs.org/Tgillard/trisquel-sugar-4.1-i686-Cloned.ovf

* '''Cleared of sugar identity; Starts on Color Selection Screen ( <===(back) to change/ customize name)'''

====[[Image:Fedora-small.jpg]] Sugar on a Stick v3 Mirabelle ====

::firstboot has not yet run; so a new user name and password will be set for the gdm login on startup for the first time
:How Built:
: '''root=sugarroot'''
: 8-GB VirtualBox hard disc
:English and English keyboard
:USA-Los Angeles (Pacific timezone)
:'''download and import 2 files:'''
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.vmdk 533M
http://download.sugarlabs.org/images/VirtualBox/Fedora-13-i686-Live-SoaS-sugaruser.ovf 12K

*Note1:Use the latest version of Oracle VM VirtualBox (3.2_10.8-64453 or later). Some appliances have multiple hard disc controllers and the earlier Sun VirtualBox 3.1 version does not support them.
*Note2: All appliances were built on a MacBook Air with Oracle VM VirtualBox (3.2.10-r66523) then tested on a Ubuntu installation on an Acer Aspire One Netbook imported into VirtualBox (3.2.10 r66523)
*Note3:Set ControlPanel/Frame "Edge" slider to far left for easier access to sugar-frame features

====[[Image:Fedora-small.jpg]] Sugar on a Stick v2 Blueberry ====

:READ FIRST: http://people.sugarlabs.org/Tgillard/soas-2-blueberry_ovf_README_FIRST.txt
:: Download these three files:
http://people.sugarlabs.org/Tgillard/soas-2-blueberry.vmdk
http://people.sugarlabs.org/Tgillard/soas-2-blueberry.ovf
http://people.sugarlabs.org/Tgillard/soas-2-blueberry.mf

====Sugar Clone====
: '''customize or duplicate Live USB installations'''
: (script files for making a customized Live USB installation self-replicating)

* '''Sugar Clone Wiki Page''' [[Sugar on a Stick/Sugar Clone]]

:Update: http://www.mail-archive.com/soas@lists.sugarlabs.org/msg02044.html
:::Rebuild/Refresh a custom SoaS iso from a running stick

=====Possible Use Cases=====
(from Wiki Page)
:'''Curriculum packaging'''
1. A teacher wants to prepare a SoaS image with a custom set of installed Activity bundles or a Journal of Activity instances for an upcoming class term.
2. The teacher modifies their current working image by adding or deleting Activity bundles from their Home view and adding or removing Journal entries with specific content
(such as a Physics model template or Etoys project), even saving distributable ebooks, or bookmarks in Browse Activity instances that are named for specific sets of local web destinations
(a class portal perhaps for deployments lacking Internet connectivity).
3. The teacher scrubs out any personal passwords or other history that should not be shared in the new copies.
4. A fresh or recycled USB stick is inserted into the computer running the customized SoaS image and the SugarClone script is executed.

:'''Full image backup or sharing'''
1. A Learner has modified their environment, perhaps adding Activity bundles and prepared specific instances such as a Activities/Physics simulation.
2. Their modifications include changes to their operating system installed through yum or RPM to obtain some new core functionality.
3. The Learner wants to archive or share this image with friends or for a backup.
4. Personal or private information is scrubbed from the Journal or Browse history and other potential stores.
5. The User creates one or more Sugar Clones.

This method of backup has the advantage that it copies Learner changes to the core operating system as well as the Journal. A LiveOS image using a separate persistent home folder could be partially cloned with either the operating system overlay or home folder without the other should that be desired.

=='''[[Build Your Own Remix with Fedora]]''' (Advanced) ==
:click this link ^ for more details and examples
:Make your own Custom CD/DVD.iso with a customized kickstart file

*Links to Trisquel, Debian and Mandriva on how to remix Live CD's
:http://trisquel.info/en/wiki/customizing-trisquel-iso
:http://wiki.debian.org/DebianCustomCD
:http://wiki.mandriva.com/en/Draklive

==XO-1 & XO-1.5==
:http://wiki.laptop.org/go/OS_images
:http://wiki.sugarlabs.org/go/Dextrose
:http://build.laptop.org/11.2.0/os9/xo-1.5/
==XO-1.75==
*ARM
:http://wiki.laptop.org/go/XO-1.75

==Fedora Sugar Bugs==
*[[Talk:Sugar_Creation_Kit|Must increase F15 RC1 netinstall Memory requirements]]
*https://bugzilla.redhat.com/buglist.cgi?component=sugar&product=Fedora
===[http://live.gnome.org/GnomeKeyring/RunningDaemon GnomeKeyring]===
:Login pops up 11 times when starting sugar-emulator:
:: https://bugzilla.redhat.com/show_bug.cgi?id=690586

==[[Development_Team/Packaging|Development Team Packaging]]==

==Sugar Bugs==
*Sugar on a Stick
:[[Sugar on a Stick Bugs]]
:[http://bugs.sugarlabs.org/query?status=assigned&status=new&status=reopened&groupdesc=1&group=milestone&component=Sugar+on+a+Stick+(SoaS)&order=priority&col=id&col=summary&col=component&col=status&col=type&col=priority&col=milestone&col=reporter&col=time&col=changetime Current Soas Bugs] satellit
*SoaS-Sugar
: http://bugs.sugarlabs.org/query?status=accepted&status=assigned&status=new&status=reopened&groupdesc=1&group=milestone&component=SoaS&order=priority&col=id&col=summary&col=component&col=status&col=type&col=priority&col=milestone&col=reporter&col=time&col=changetime (fgrose)

*0.90-olpc
:http://bugs.sugarlabs.org/query?status=accepted&status=assigned&status=new&status=reopened&order=priority&col=id&col=summary&col=status&col=type&col=priority&col=milestone&col=component&keywords=~olpc-0.90 (pbrobinson)

EduJAM/2011

2011-03-31T10:55:52Z

Bert: /* Uruguay */ fix buquebus.com link

{{Translations}}
[[File:Edujam-logo-para-email-3.png]]

'''Home page of the summit: http://edujam2011.ceibaljam.org'''

This page is for planning the summit in Uruguay May 5th to 7th 2011.

'''Don't forget the [[Conozco Uruguay Tour|pre-summit tour Apr 30 - May 4/5,]] as well as post-summit codesprint May 8/9 onwards -- dates are final but details are evolving!'''

== Main goals ==
* '''Focus on developers'''. It does not mean at all we're not concerned about educational aspects, but as a developers community we have huge challenges and the summit will be more of a working instance than a "reflection" instance.
* '''Exceed OLPC and Sugar'''. The developers community goes beyond OLPC and Sugar, and this could be a good instance for bringing "non-olpc organizations" to the conversation.
* '''Focus on South America'''. Bring as many south american developers as possible to Uruguay.

== Program ==
A first sketch of the event (''preliminary,'' [http://ceibaljam.org/drupal/?q=node/1127 see also update here!]) is as follows:

Thu 5th:
* 18:00 Opening

Fri 6th:
* 9:00 Keynote speaker(s)
* 10:30 Workshops and talks in 2 tracks (general topics)
* 13:00 Lunch
* 14:00 Workshops and discussions in 2 tracks: 1) Sugar activity development, and 2) [[Sugar Camp Q2 2011|Sugar future]]
* 19:00 Friday night social

Sat 7th:
* 9:00 Deployment exchange
* 11:00 Unconference
* 13:00 Lunch
* 14:00 Unconference
* 18:00 Formal Event Closing

Sun 8/9 ONWARDS: (Optional but encouraged! Separate venue/location possible...)
* 9:00 Hackfest/Codesprint til you drop!

Program committee:

* Andrés Ambrois
* Walter Bender
* Gabriel Eirea
* Pablo Flores
* Gonzalo Odiard
* Fernando Sansberro

== Pre-Summit "Conozco Uruguay" Exploration Tour ==
We're organizing a set of in-person activities for those who want to know more about the Uruguayan/Ceibal experience, visiting different points of the country, meeting with families, teachers, etc.

This will happen during the 5-6 days prior to the summit (from Saturday April 30th to Thursday May 5th) for independent and resilient travelers, committed to "anthropological" learning through patient exploration -- [[Conozco Uruguay Tour|details are emerging here!]]

== Attendees ==
Attendees and possible attendees list in: http://ceibaljam.org/drupal/?q=node/1108 
If you want to attend, please write us: edujam2011@ceibaljam.org

Including Volunteer Organizers: Martín Abente, Walter Bender, Gabriel Eirea, David Farning, Pablo Flores, [[user:Holt|Adam Holt]], Bernie Innocenti, Aleksey Lim, Anish Mangal, Gonzalo Odiard, [[user:aa|Andrés Ambrois]]

== Accommodation ==
We'll put here some information about possible places for staying. At the same time we'll make a volunteers hosting program, so Uruguayan volunteers can host some of the attendees. More information soon.

Uruguay (generally) uses [http://treehouse.ofb.net/go/en/voltage/Uruguay 220V European] [http://www.adaptelec.com/index.php?main_page=document_general_info&products_id=252 electrical outlets] so please consider bringing a small converter.

Wifi access will be sought where possible, but not guaranteed.

== Registration ==
[http://ceibaljam.org/drupal/?q=edujam2011_en Registration is now Open!]

As explained therein, pricing is $100, with confirmed volunteers/students paying $30 or $10. Attendance will likely be limited to about 100 attendees maximum.

Flight prices will rise, so we strongly encourage you to book your flight to Montevideo (MVD) & register today!

== Uruguay ==

Visas are [http://worldtravelguide.net/uruguay/passport-visa not required] for most US, Canada, Europe, Australia citizens.

Direct flights to Montevideo (Carrasco Airport) from:
* US: Miami
* Europe: Madrid
* Most of South America
* Nearby hubs: Buenos Aires, Sao Paulo, Santiago
There are also nice ferries from Buenos Aires: http://www.buquebus.com/

An airport departure tax of $30+ may be charged upon leaving Uruguay, if not pre-paid within your flight ticket.

Touristic information: http://www.turismo.gub.uy

Don't forget to register for "Conozco Uruguay", our [[Conozco Uruguay Tour|pre-summit eduTRIP!]] (Saturday April 30 - Thursday May 5)

==Discussion==

Caryl Bigenho has posted some really great suggestions & topics on the [[Talk:Uruguay_Summit_2011|Talk Page]] -- eg. she started with "fun" activities for teachers, students, and parents to participate in alongside software architects -- please join her to [[Talk:Uruguay_Summit_2011|share your own ideas, for things you'd like to do at EduJAM!]]

Development Team/Low-level Activity API

2010-12-14T18:51:22Z

Bert: /* Querying */ add query syntax reference

<noinclude>{{Developers}}{{TOCright}}</noinclude>

Sugar activities are usually written in Python using the [http://api.sugarlabs.org/ Python Activity API]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. The discussion below tries to be language-agnostic.

''This documentation effort was started by [[User:Bert|Bert]] on the [http://wiki.laptop.org/go/Low-level_Activity_API OLPC wiki] while implementing the [[olpc:Squeak|Squeak]]-based [[Activities/Etoys|Etoys]] activity. Please fill in missing pieces and correct mistakes!''

See [[olpc:Activity Development Alternatives]] for an overview of various ways to develop activities.

As Sugar evolves to become compatible with ordinary X11 programs, and as services like collaboration migrate into generic X11 desktops, this document will become less and less relevant. All the special rules for "Sugar Activities" will fall by the wayside, because any X11 program will be usable with Sugar. This will greatly simplify both the job of Activity authors, and the usefulness of Sugar-based computers (which will have access to thousands of X "applications" that have never heard of Sugar and never will).

=Overview=
An Activity is basically a regular X11 program which communicates with the special Sugar services via D-Bus.

The [[Development Team/Almanac/Activity Bundles|Activity bundle]] specifies an executable. For each [[#Activity Instance|activity instance]], that executable is run with arguments specifying the bundle id (taken from the bundle) and activity id (generated by Sugar). The instance opens an X window, putting these ids into window [[#X Properties|properties]]. It also needs to provide a D-Bus [[#D-Bus Methods|service]] to receive messages from Sugar. An activity must retrieve and store its state in the [[#Datastore|datastore]], implement [[#Presence|sharing]] on the mesh network, and be [[#Security|security]] compliant.

==Activity Life Cycle==
Please see [[Human Interface Guidelines/Activities/Activity Basics|Activity Basics]] for the user's point of view. The programmer's point of view is outlined here, and detailed in the following sections:

'''Start Up'''
# The activity is executed.
# It creates a D-Bus service to receive method calls from the Sugar shell.
# It creates an X11 window with special properties so the Sugar shell can associate an activity with its window.
# If an object id was passed on the command line, the activity loads that object from the Datastore. Otherwise, it creates a new Datastore object.
# The activity asks the Presence Service to find out if it is shared. If so, it joins the shared activity.

'''Operation'''
# The activity continuously handles X11 user input, as well as D-Bus messages from the Sugar shell, or signals from other sources like the Presence Service.
# Whenever the state of the activity was altered significantly, it should update its Datastore object to prevent data loss on an unexpected shutdown.
# If the user indicates wanting to share the activity, it has to announce this to the Presence Service.
# If the view-source key is pressed, some meta-action about the activity should be invoked, like showing its source code.

'''Shut Down'''
# When the activity window is closed, it updates its Datastore object with its current state.
# It leaves the shared activity (if shared),
# and then quits.

=Activity Instance=

When the activity instance is executed, the current working directory will be set to the bundle directory (e.g., ~/Activities/MyActivity.activity) so resource files can be accessed using relative paths. Also, its "bin" subdirectory is added to the PATH.

==Command Line Arguments==

The following arguments are passed to the executable:

; -b, --bundle-id : Identifier of the activity bundle. Must be made available as [[#X Property|window property]].
; -a, --activity-id : Unique identifier of the activity instance. Must be made available as [[#X Property|window property]], and is used to create the [[#D-Bus Methods|D-Bus service]].
; -o, --object-id : (optional) Identity of the journal object associated with the activity instance. When you resume an activity from the journal the object id will be passed in (see [[#Datastore|datastore]]).
; -u, --uri : (optional) URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages).

==Environment Variables==

Some environment variables are setup before the activity is launched:

SUGAR_ACTIVITY_ROOT

Writable space for the activity, see [[#Security|security]]. Activities are prohibited from writing anywhere else in the file system.

SUGAR_BUNDLE_PATH

Path to the current activity bundle (e.g., /usr/share/activities/MyActivity.activity or ~/Activities/MyActivity.activity). This is also the current working directory when the activity is started, so relative paths can be used to access files inside the bundle, rather than constructing absolute paths using this variable.

==X Properties==
The activity instance needs to set some properties on its top-level window, '''before''' the window is shown on the screen (see [http://dev.laptop.org/ticket/5271 #5271]):

_SUGAR_BUNDLE_ID

The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

_SUGAR_ACTIVITY_ID

The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt> as passed on the [[#Command Line Arguments|command line]].

:The above properties need to be on the window before it pops up. This is easy when programming with raw libX11, but often difficult with high-level toolkits. E.g., in GTK you can use the "realize" event. The toolkit is likely to create and pop up the window in one operation, so you don't get a chance to set the properties. A workable solution is to piggyback on a function within the toolkit. For example, you can implement XChangeProperty in your activity. Using dlsym() with the RTLD_NEXT flag, you can obtain a function pointer to the normal XChangeProperty function in libX11. Your implementation normally just calls that. The first time your implementation is called though, it also sets up the sugar-specific properties. Essentially you are supplying a callback function to a toolkit that was never intended to call one. ''Once [http://dev.laptop.org/ticket/5271 #5271] is settled, this hack is not necessary anymore''

Also, some Window Manager hints need to be set:

_NET_WM_NAME

should be set to the current activity title. It usually corresponds to the title which is displayed in the journal and advertised on the network for shared activities. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511086 Freedesktop specification].

_NET_WM_PID

must be set to the activity's process id so the shell can associate memory usage with an activity. See [http://standards.freedesktop.org/wm-spec/wm-spec-latest.html#id2511925 Freedesktop specification].

==D-Bus Methods==
An activity instance needs to create a D-Bus service:

Service name: org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f # no dot after Activity!
Object path: /org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f
Interface: org.laptop.Activity

(where <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> is the activity id as passed on the cmd line)

It must support the following methods:

org.laptop.Activity.SetActive(b: active)

Activate or passivate an activity. This is sent when switching activities, there is only one active activity at a time, all others are passive. A passive activity must immediately release resources like sound, camera etc. Also it should prepare for being killed without warning at any time in the future (see [[olpc:OOM|OOM]]) by auto-saving to the datastore.

org.laptop.Activity.Invite(s: buddy_key)

If not yet shared, share this activity privately because the user chose "invite" from the mesh view. Then, invite the buddy (see [[#Inviting|below]]).

The following methods are '''optional''':

org.laptop.Activity.HandleViewSource()

The user wants to view the source. If this method does not answer an error, the activity will handle viewing the source code itself, otherwise Sugar will show the source.

org.laptop.Activity.GetDocumentPath():s

Answer the path of a document source file to view, in addition to the activity bundle itself. Sugar will delete that document when the view-source interface is closed. This method is only called when Sugar handles the source viewing.

== Session ==

To communicate to an activity when it needs to save data and quit, we use the [http://www.xfree.org/current/xsmp.pdf X Session management protocol]. The part of the protocol which deals with application restarting is not used and we don't plan to implement it.

In the Glucose 0.84 release cycle we are planning do add support for a D-Bus based protocol which is currently being developed for the GNOME desktop. You can read about it on this [http://bugzilla.gnome.org/show_bug.cgi?id=535829 bugzilla report].

=Datastore=

An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service:

Service name: org.laptop.sugar.DataStore
Object path: /org/laptop/sugar/DataStore
Interface: org.laptop.sugar.DataStore

==Meta Data==
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties:

'activity': 'my.organization.MyActivity' # bundle id (determines icon and default activity)
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f'
'title': 'My new project' # as shown in journal
'title_set_by_user': '0' # '1' if not default title
'keep': '0' # '1' if marked as "favorite" (star)
'ctime': '1972-05-12T18:41:08' # created (local time)
'mtime': '2007-06-16T03:42:33' # modified (local time), deprecated but still used internally so must be present
'timestamp': 1192715145 # modified (UTC), in seconds since the UNIX epoch, must be present
'preview': ByteArray(png file data, 300x225 px)
'icon-color': '#ff0000,#ffff00' # owner buddy or shared activity color
'mime_type': 'application/x-my-activity'
'share-scope': # if shared
'buddies': '{}' # buddies in a shared activity as JSON
'description': 'some longer text' # description editable in journal detail view
'tags': 'one two' # tags editable in journal detail view
'something:text': 'text I want to be indexed' # properties with key ending in ":text" will be searched in fulltext search
'checksum': # md5 hash of file, created by DS, do not set or modify
'my.organization.MyActivity.myProperty' # private property, prefixed with activity name to avoid name clashes

''Due to bug [http://dev.laptop.org/ticket/4662 #4662] only some known properties are retained! The list is at the bottom of [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/625c4f13624d52abdc9c1cc26f9b63342ac400c7/src/olpc/datastore/model.py#line379 datastore/model.py] (fixed in Sugar 0.83)''

''And custom properties must have String values for now (bug [http://dev.laptop.org/ticket/5134 #5134]).''

''And since Sugar 0.83 all former String values are now stored and returned as Arrays of Bytes. You can still set them as Strings.''

==Keeping and Resuming==

To create an item in the datastore, call create():

object_id = datastore.create(properties, filename, transfer_ownership)

The metadata properties are a dictionary (type "a{sv}") containing (at least) the entries mentioned above. If filename is not empty, the file will be moved or copied to the datastore, depending on the transfer_ownership flag. The activity should delete the file once the call completes (if transfer_ownership was false). Otherwise (if transfer_ownership was true) the datastore will remove the file. ''For this to work under rainbow you must place the file in the [[#Writable Directories|"instance" directory]].'' The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'.

To update an item use update():

datastore.update(object_id, properties, filename, transfer_ownership)

Again, if a filename was given and transfer_ownership is false, the activity is responsible for deleting the file after the call returns.

To retrieve an object's properties and file:

properties = datastore.get_properties(object_id)
filename = datastore.get_filename(object_id)

The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits.

The metadata properties need to be preserved and stored again when updating an entry. An activity should also track updates to the properties made in the Journal while editing the datastore object. For this it should subscribe to the Updated signal:

datastore.Updated(object_id)

:An efficient way to do this is registering a DBus match like <tt>path='/org/laptop/sugar/DataStore', member='Updated', interface='org.laptop.sugar.DataStore', type='signal', arg0='objectId'</tt> --[[User:Bert|Bert]]

==Querying==

Activities may query the datastore:

(results,count) = datastore.find(query, properties)

It returns the matching object's metadata as array of dictionaries, and a count of matching items (the array may have fewer items if the query was limited). In addition to the usual metadata items, each dictionary will include the object id at key 'uid', the mountpoint of the item at key 'mountpoint', and possibly a 'filename' if requested.

The '''properties''' argument is an array of strings. It defines which keys to include in the results. You should only specify the keys you actually need. If you pass an empty array here, all the metadata would be returned, which for a Journal with hundreds of entries and previews could amount to multiple megabytes of data.

The '''query''' argument is a dictionary. If empty, all the datastore's entries will be returned, but again, you should avoid that. The key-value pairs specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.:
: 'title' = 'First Project' (but see note below)
: 'mime_type' = ['image/png', 'image/jpeg']
: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'}
A few specific keys adjust the query:
: 'query': fulltext search term (supports some [http://xapian.org/docs/queryparser.html special operators])
: 'order_by': sort key (or array of keys) to order results by, to reverse order use '-key' (but see note below)
: 'limit', 'offset': return only limit results starting at offset
: 'mountpoints': array of [[#Mount Points|mountpoint ids]] to search (or all if not specified)
: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added.

NOTE: In Sugar 0.82 you cannot search for 'uid'. Since Sugar 0.84 only very few keys are supported in the query ('uid', 'activity', 'activity_id', 'mime_type', and 'keep', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line32 here]). Other keys are ignored so you may get back more results than expected. Results are ordered by timestamp by default. Sort keys are limited, too (none in 0.84, in 0.86 'timestamp' and 'title', see [http://git.sugarlabs.org/projects/sugar-datastore/repos/mainline/blobs/master/src/carquinyol/indexstore.py#line266 here]).

You can also retrieve an array of unique values for a field:

values = datastore.get_uniquevaluesfor(property, query)

''NOTE: currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. And in more recent Sugar versions, the only property allowed is 'activity'.''

==Watching==

To keep cached information in your activity up-to-date, you can subscribe to these signals:

datastore.Created(object_id)
datastore.Updated(object_id)
datastore.Deleted(object_id)

E.g. if you display a document title in your activity, and the user changes that entry in the Journal while your activity is running, you can use the Updated signal to reflect that change. Otherwise, when you save the document, it will overwrite the title set by the user.

Similarly, if you display a list of Journal entries in your activity, it would have to be updated in response to the Created and Deleted signals.

==Progress Display==

To add a progress bar to a Journal entry (like the Browse activity does while downloading files), create an entry with a "progress" property in the meta data. The value is the percentage done (0 to 100). The file cannot actually be stored incrementally in the datastore, it needs to be saved to a temp file first. But the entry metadata can be updated continuously to inform the user of progress while creating the temp file (by not giving a filename yet in the update() call). Once the temp file is complete, it can be checked-in as usual. The user can cancel by clicking the x icon next to the progress bar. This deletes the entry, so you need to watch for the datastore's "Deleted(id)" signal.

meta = ... # regular metadata
meta["progress"] = 0
id = datastore.create(meta, "") # create with progress bar
while (done() < 100) {
if (got_signal(datastore, "Deleted", id))
return user_cancelled();
write_to(tmpfile)
meta['progress'] = done()
datastore.update(id, meta, "") # update progress bar
}
meta.deleteKey("progress")
datastore.update(id, meta, tmpfile.name) # check-in file, remove progress bar

==Journal UI==
The Journal activity provides a D-Bus service to allow activities to bring up an object chooser dialog, focus searches etc.:
Service name: org.laptop.Journal
Object path: /org/laptop/Journal
Interface: org.laptop.Journal
===Choosing Objects===
Call this method to bring up the Chooser dialog (which looks like a small journal overlayed on your activity):
chooser_id = org.laptop.Journal.ChooseObject(xid, what_filter) # only xid arg supported in Sugar 0.82!
The xid should be your activity's X window handle, or <tt>0</tt>. The filter says what type of Journal entries is preselected in the drop-down menu (''this parameter was added in Sugar 0.83''). It's a string containing either a bundle id (e.g., <tt>'my.organization.MyActivity'</tt>), or one of the generic data types (<tt>'Text', 'Image', 'Video', 'Audio', 'Link'</tt> [http://git.sugarlabs.org/projects/sugar-base/repos/mainline/blobs/master/src/sugar/mime.py#line32 definition]), or an empty string for no filter. The call returns immediately with a string chooser_id. You need to watch these signals which get emitted when an item is chosen or the dialog is canceled:
ObjectChooserResponse(chooser_id, object_id)
ObjectChooserCancelled(chooser_id)
The object_id received in an ObjectChooserResponse signal then can be used to open the corresponding [[#Keeping and Resuming|datastore object]].

===Focusing Objects===
The Journal activity allows an activitiy to "focus" an object, so the user can immediately open it (this is currently the only way to have one activity "launch" a different activity).

org.laptop.Journal.ShowObject(object_id)

Switches to the Journal activity and shows the selected object.

This can be used to, e.g., open a URL (create a URL object in the journal then call this) or to view source code (store the source code as text file in the journal then call ShowObject() on it).

<s>To focus on multiple objects: <code>org.laptop.Journal.FocusSearch(query)</code></s> ''Removed in Sugar 0.83''

==Mount Points==
Devices are represented as mount points in the datastore. If no mountpoint is explicitly specified, the main datastore (Journal) is used.

mounts = datastore.mounts()

Returns an array of mount point descriptors where each descriptor is a dictionary containing at least the following keys:
:'id': the id used to refer explicitly to the mount point
:'title': Human readable identifier for the mountpoint ''(in Sugar 0.82, just the uri)''
:'uri': The uri which triggered the mount

Mount points can be specified when creating an object (using a 'mountpoint' key and id value in the properties), and when querying the datastore (by adding a 'mountpoints' query option).

Large files to be stored on an external device should be placed at the uri of the mount point (see [[#External Media|external media]]).

'''Note:''' ''This only works as described in Sugar up to 0.82. The functions do exist in later Sugar versions, but do not return useful data.''

=Security=

Activities are isolated from each other and from the "olpc" user. They do not have the same permissions as you would expect in a non-restricted Linux environment (see [[olpc:OLPC Bitfrost|Bitfrost]] and [[olpc:Rainbow|Rainbow]]). In particular, they can '''not''' write in the /home/olpc directory!

== Users and Groups ==

While Sugar runs as user "olpc", activities do '''not''' (the [[olpc:Terminal|Terminal]] activity as a maintenance tool is an exception).

Instead, each activity instance is run with a unique user id. That is, a new anonymous user is created when the user clicks an activity icon, and the [[olpc:Rainbow|Rainbow]] demon runs the activity under that user.

All instance of the same activity get the same unique group id. That is, a new anonymous group is created when the activity is run for the first time, each subsequent activity launch will use the same group id. This means files to be shared for all instances of an activity must be made group-accessible.

== File Access ==

=== Home Directory ===

Since each activity is run as a different user, it gets a different home directory on each invocation. In release 8.2, the home directory for an activity equals the $SUGAR_ACTIVITY_ROOT/instance/ directory (see below). For data such as config files to survive and be accessible by all future activity invocations, they must not be stored in $HOME but rather $SUGAR_ACTIVITY_ROOT/data/ should be used.

: Hint: A trick to help porting legacy software which expects its config files to be in the home directory is to export HOME=$SUGAR_ACTIVITY_ROOT/data in an activity's launch script. --[[User:Bert|Bert]]

=== Writable Directories ===
All writing to the file system is restricted to subdirectories of the path given in the SUGAR_ACTIVITY_ROOT environment variable. This directory has three subdirectories with different policies:

;$SUGAR_ACTIVITY_ROOT/data/: This directory is used similar to a traditional home directory, for persistent activity data such as configuration files. Make sure files in there are group readable and writable (see [[#Users and Groups|users and groups]]). The directory itself is group-writable. Files stored here will survive reboots and OS upgrades.

;$SUGAR_ACTIVITY_ROOT/tmp/: This directory is used similar to a /tmp directory, being backed by RAM. It may be as small as 1 MB. This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die). This directory is ''only'' accessible to the activity and its children; not even to Sugar.

;$SUGAR_ACTIVITY_ROOT/instance/: This directory is used similar to a /var/tmp directory, being backed by flash rather than by RAM. It is unique per instance. It is used for transfer to and from the datastore (see [[#Keeping and Resuming|keeping and resuming]]). This directory is deleted when the activity exits (specifically, as soon as all children of the activity's first process die)

As of version 8.2, all the activity root directories are created in /home/olpc/isolation and can be examined there with the Terminal activity. However, activities MUST use the $SUGAR_ACTIVITY_ROOT variable because the isolation directory layout is expected to change.

=== Concurrency ===

Multiple instances of an activity may communicate with one another through their shared 'data' directory; however, since each instance runs as a different user, [[olpc:Concurrent activity instances|some care must be taken]] ([http://dev.laptop.org/ticket/5476 #5476]) when sending messages to other activities through this shared medium.

=== External Media ===

External media (USB drives, SD cards) are auto-mounted by the Journal and appear in /media/*. No access restrictions are applied currently (up to release 8.2). If activities use these external media directly (rather than through the Journal, see [[#Mount Points|mount points]]), they need to take care of ensuring data integrity since the user may (and will) remove the medium at any time.

== Signing ==

An activity will have to be cryptographically signed to allow secure activity upgrades once they are on the machines. Tools for this will be provided soon. See discussion of [[Development Team/Almanac/Activity Bundles#Bundle Structure|contents.sig]].

''to be detailed''

== Permissions Declarations ==

Permission declarations will enumerate which special permissions (camera access? microphone access? non-Tubes network access? etc.) your activity may need for its normal operation. See [[Development Team/Almanac/Activity Bundles#activity/permissions.info|permissions.info]] and generally [[olpc:OLPC Bitfrost|Bitfrost]].

''to be detailed''

=Presence=

Collaboration plays a large role in Sugar. Still, the presence and sharing APIs are still somewhat rough. There are attempts to explain sharing, see [[olpc:Activity sharing|Activity sharing]]. The following are the bare essentials.

==General==

Activities must support sharing using the [[olpc:Presence Service D-Bus API|Presence Service]] (PS). It is accessible on the D-Bus:

Service: org.laptop.Sugar.Presence
Interface: org.laptop.Sugar.Presence
Object Path: /org/laptop/Sugar/Presence

===Sharing===

If the activity was not yet shared but the user clicked the Share button, sharing is initiated by calling ShareActivity():

activity = PS.ShareActivity(activity_id, bundle_id, name, properties)

The bundle id is used for the icon and to launch the same activity when someone joins it. The name will be shown in the mesh view and should generally be the same as the title of the datastore object (see above). The properties argument is not used currently (but see [http://dev.laptop.org/ticket/4660 #4660]) and should be an empty dictionary.

Note that sharing will be private (invitation-only) by default, that is, the icon will not be visible in the mesh. To share publicly, set the 'private' property to False:

activity.SetProperties({'private': False})

===Inviting===
Another way of starting a shared session is by inviting a buddy from the mesh view. The Invite() method of the activity is called (see [[#D-Bus_Methods|above]]). Then the activity should be shared privately, and the buddy must be invited using the key that was passed to Invite():

buddy = PS.GetBuddyByPublicKey(buddy_key)
activity.Invite(buddy, message)

===Joining===

When launching, the PS must be consulted to see if this instance was shared by someone else, meaning it was launched by the user is trying to join it:

activity = PS.GetActivityById(activity_id)

This yields an error if this instance (identified by its activity id) was not shared, in which case a regular non-shared startup should be performed. Otherwise, the activity object held by the PS is returned, and this activity instance needs to join:

activity.Join()

It should continue by establishing a communication channel with the originating instance (see below)

=== Leaving ===

To leave a shared activity (e.g. because it is closing) you need to inform the PS:

activity.Leave()

==Buddies==

The activity object created by either sharing the current activity or joining an existing activity is used to establish means of communication between these instances. The joined XOs can be accessed to start communicating with them:

buddies = activity.GetJoinedBuddies()

To get notified of buddies joining or leaving, listen to these signals:

BuddyJoined (o: buddy)
BuddyLeft (o: buddy)

==Tubes==
"Tubes" are the transport medium of choice on the XO, provided by the [http://telepathy.freedesktop.org/ Telepathy] framework. There are "D-Bus Tubes" allowing remote D-Bus calls, and "Stream Tubes" which forward sockets (similar to ssh forwarding). Tubes are collected in a "Channel", and channels are associated with a "room", one per shared activity instance.

First, get the Telepathy connection from the shared activity object:

(tp_service, tp_connection, channels) = activity.GetChannels()

where tp_service and tp_connection is the D-Bus service name and object path for the Telepathy [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Connection connection]. An array of [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel channels] pre-created in the activity room is returned, too. There is at least a text chat and a tubes channel at

Service: (tp_service)
Object path: (channels[i])
Interface: 'org.freedesktop.Telepathy.Channel'

Use GetChannelType() to tell the channels apart:

if (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Tubes')
...
elseif (channel.GetChannelType() == 'org.freedesktop.Telepathy.Channel.Type.Text')
...

===Stream Tubes===
A stream tube forwards a socket to a remote host (similar to ssh forwarding, but not encrypted). The activity can set up a listening socket by whatever means and then create a tube to forward it:

tube_id = channel.OfferStreamTube( # sa{sv}uvuv -> u
'service-name', # well-known TCP service name conforming to RFC 2782, see [http://www.dns-sd.org/ServiceTypes.html]
{}, # dict of params
2, # socket type (0=Unix, 2=IPv4, 3=IPv6)
('127.0.0.1', 12345), # socket address (depends on type)
0, 0) # access control & params

You can forward Unix, IPv4, or IPv6 sockets. Access control is restricted to localhost by default.

New tubes are announced by a signal:

NewTube ( u: tube_id, u: initiator, u: type, s: service, a{sv}: parameters, u: state )

and you can list all available tubes:

tubes = channel.ListTubes() # -> a(uuusa{sv}u), same as in NewTube signal

To connect to a tube:

address = channel.AcceptStreamTube( # uuuv -> v
tube_id,
2, # socket type to return (0=Unix, 2=IPv4, 3=IPv6)
0, 0) # access control & params

which returns an address struct of the specified type, e.g., ('127.0.0.1', 45679). Then just connect a socket to that address and you are ready to share data.

===D-Bus Tubes===
''to be continued. In the mean time, see [[olpc:Presence Service D-Bus API]] and [http://telepathy.freedesktop.org/spec-0.16.html#org.freedesktop.Telepathy.Channel.Type.Tubes Tubes]''

[[Category:API]]
[[Category:Collaboration]]

Oversight Board/2010-2011-candidates

2010-10-31T13:31:53Z

Bert: Undo revision 58692 by MartinDengler (talk)

<noinclude>{{GoogleTrans-en}}</noinclude>

==Election==
Three (3) seats are open ([[Sugar Labs/Governance#Oversight_Board|due to staggered seat terms]]) for election / re-election to the [[Oversight Board|Sugar Labs Oversight Board]] for 2010-2011: [[User:cjb|Chris Ball]], [[User:Holt|Adam Holt]], [[User:SeanDaly|Sean Daly]]'s seats.

==Candidates==
Here are the candidates:

* [http://google.com/search?q=adam+holt+mit Adam Holt] ([[User:Holt|7-point platform]], [http://lists.sugarlabs.org/archive/iaep/2010-October/011885.html look-reform-in-the-eye proposal])
* [[User:SMParrish|Steven Parrish]]
* [[User:cjb|Chris Ball]]
* Rosamel Norma Ramirez Mendez ([http://www.blogedu-rosamel.blogspot.com/ blog])
* Gerald Ardito ([http://web.me.com/geraldar/The_Shape_of_Disruption/Welcome.html/ doctoral work website])
* [[User:Sebastian|Sebastian Silva]]
* [[User:Alsroot/SLOBs_election_platform|Aleksey Lim]], [[User:Alsroot/Sugar_Architecture|"Sugar Architecture"]]
* [http://wiki.laptop.org/go/User:Claudia_Urrea| Claudia Urrea]

==Candidate list is OPEN==

PLEASE ADD YOUR NAME and a link to some background information or position statement.

==Candidate list CLOSING deadline==

The candidate list will be CLOSED (frozen) on November 1st 11:59PM [http://www.timeanddate.com/library/abbreviations/timezones/na/edt.html EDT], 2010)

==References==
* [[Oversight_Board/2009-2010-candidates]]
* 23 September 2009 - [http://lists.sugarlabs.org/archive/iaep/2009-September/008620.html Oversight Board election procedure update]
* [[Archive/Current Events/2009-08-05#Help_wanted]]
* [[Sugar Labs/Members]]

[[Category:Oversight board]]
[[Category:Governance]]

[[Category:Team]]

0.90/Notes

2010-10-01T08:40:31Z

Bert: /* Etoys */

<noinclude>{{ Translations | [[0.90/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]
Sucrose 0.90 Release Notes

== Introduction ==
Sucrose 0.90 is the latest version of the Sugar learning environment: Sugar's focus is ease of use, stability, and first-class internationalization. Sugar is Free and Open Source Software and provides tools for learning. Furthermore, Sugar provides a flexible and powerful platform for activity developers. Sugar consists of [[Taxonomy#Glucose:_The_base_Sugar_environment|Glucose]], the base system environment; and [[Taxonomy#Fructose:_The_set_of_demonstration_activities|Fructose]], a set of demonstration activities. This new release contains many new features, performance and code improvements, bug fixes, and translations.

== What is new for users ==
=== Remove the Presence Service ===
Tomeu Vizoso from Collabora has been doing a great work to remove the [[Features/Remove_Presence_Service |Presence Service]]. There are no directly visible changes for the user but the overall collaboration experience should be more stable.

=== Sugar Ad-hoc networks ===
To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. The [[Features/Sugar_Adhoc_Networks| Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. Simon Schampijer from OLPC has been working on this Feature and back ported it as well to Sugar 0.84.

=== Enhanced color selector ===
A new [[Features/Enhanced color selector| color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. Originally proposed for 0.88 this Feature went through several design iterations and finally consensus was reached. Now, we are excited to hear what the learners think about it.

=== Spiral Home View ===
Walter Bender has been working on another Feature during this cycle. [[Features/Spiral_Home_View |The Spiral Home View]] is an enhancement to the Home View to enable the display of more icons. The idea is that after the circle becomes too large, rather than shrinking the icons, it morphs into a spiral.

=== New ordering options in the Journal ===
Andrés Ambrois has been adding [[Features/Journal_Sort | new filtering options]] to the Journal. You can order now by size, creation date and modification date. The Feature originally implemented for [[Dextrose]] and sponsored by [http://activitycentral.org activity central] has been found it's way successfully into 0.90, too.

=== New Keybindings for the Frame and Journal ===
Daniel Drake has been adding keybindings for the Journal (F5) and the Frame (F6). This will help to access those important views quicker on hardware where there is no designated key.

=== Turtle Art ===

The most visible changes are the incorporation of some new blocks, such as the 'Fill' block for created filled polygons, Gray, Black, and White blocks, and the 'Turtle Sees' block, that enables the turtle to directly interact with its canvas. There is also a [http://turtleartsite.appspot.com/ new site] for uploading and downloading Turtle Art projects.

<gallery>
File:TAMaze.png|Turtle 'sees'
File:Turtle Art Site.png|http://turtleartsite.appspot.com/
</gallery>

Please see [[0.90/TurtleArt]] for more details.

=== Etoys ===
Sugar 0.90 includes the latest Etoys release. Some of the new features in Etoys 4.1 are DrGeo, speech bubbles, a timer tile and persistent preferences. Also, the QuickGuides have been translated into several languages.
<gallery>
File:Etoys41-DrGeo.png|DrGeo in Etoys
File:Etoys41-Bubble.png|Speech Bubbles
File:Etoys41-Guide.png|Translated QuickGuide
</gallery>
An important change is that projects are not saved automatically anymore when you exit the Etoys activity. Instead of the regular Stop button, you will see an Exit button:

[[File:Etoys41-Exit.png‎]]

Find out more in the [http://squeakland.org/download/releaseNotes.jsp Etoys 4.1 release notes].

=== Sugar Activities ===

While we bundle a small subset of the Sugar Activities within Sucrose, most of the Activity "activity" can be tracked by visiting [http://activities.sugarlabs.org the Sugar Activity Library].

We have recently surpassed ''3.6-million'' Sugar Activity downloads! There are ''hundreds of activities'' available for download in a variety of categories!

Thanks to '''''all''' the activity maintainers and developers'' for making this happen.

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Category !! No. of Activities
|-
|Search & discovery||36
|-
|Documents||13
|-
|News||3
|-
|Chat, mail and talk||6
|-
|Media creation||25
|-
|Programming||13
|-
|Maths & science||85
|-
|Maps & geography||5
|-
|Media players||1
|-
|Games||60
|-
|Teacher tools||107
|}

==== Recent additions ====
[http://activities.sugarlabs.org/en-US/sugar/browse/type:1/cat:all?sort=newest Recent additions] include:

<gallery>
File:DrGeo.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]
File:Pukallanapac.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]
File:ConstellationsFlashCards.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]
File:Gtranslator.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]
File:Words.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]
File:VNClauncher.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]
File:SunMoonMusicMC.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]
File:GetBooks.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]
File:StarChart.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]
File:XaoS.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]
File:TurtleArtMini.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]
File:SuperTux.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]
File:Nepohualtzintzin.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]
File:SlideruleA.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]
</gallery>

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Activity !! Description
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]||Dr. Geo is an interactive geometry activity. Dr. Geo allows one to create geometric figure plus the interactive manipulation of such figure in respect with their geometric constraints. It is usable in teaching situation with students from primary or secondary level. It is simple and effective with some unique features as scripting and Smalltalk programming.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]||A puzzle: Move the pieces until the circles are all solid circles.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]||This program teaches the constellations by means of a flash-card-like interface. The program draws a constellation and the student has to pick the correct name from a list of five possible choices.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]||A Sugarized version of the translation file editor "Gtranslator" The GTranslator activity allows to translate the po files locally. This should allow users without a permanent Internet access to translate off-line the localization files downloaded from the Pootle translation server and to contribute to the localization of Sugar to their own language.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]||A multi-lingual dictionary with speech synthesis.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]||This activity helps you broadcast your screen to another computer. It will automatically launch a VNC server (X11vnc) and display your IP address. You can then connect and view the screen of Sugar on another conmputer using any VNC client (e.g. TigerVNC, UltraVNC Viewer, RealVNC, etc).
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]||Sun-Moon Music MC - Realtime Sonic Environments for Children, Multiple MIDI Controller version. Collaborative exploration and performance encouraged. Requires 1 or more MIDI controllers. This version of Sun-Moon Music is especially designed for collaborative exploration and performance. All MIDI control devices must be set to the same channel.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]||The Get Books activity lets users search and retrieve books from a variety of sources (Internet Archive, Feedbooks, etc). It supports the OPDS protocol for book discovery.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]||This activity will display a map of the sky showing the position of the visible stars, some of the larger and brighter deep-sky objects (DSOs), the "classical" planets, the sun and the moon.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]||XaoS is an interactive fractal zoomer. It allows the user to continuously to zoom in or out of a fractal in a fluid, continuous motion. This capability makes XaoS great for exploring fractals, and it’s just plain fun!
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]||Turtle Art Mini is a simple graphical programming environment. It is modeled on the Logo programming language and it emphasized graphical expression by learners new to programming. (Turtle Art Mimi is a subset of the [http://activities.sugarlabs.org/en-US/sugar/addon/4027 Turtle Art] activity – AKA Turtle Blocks)
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]||A Sugar clone of the Super Tux game.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]||Abacus is a simple, customizable abacus activity for Sugar.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]||Sliderule is a simple, customizable slide rule activity for Sugar.
|}

==== New experimental activities ====
These are activities under development that may be of interest to Sugar users:
<gallery>
File:ProducePuzzle.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4322 Produce Puzzle (experimental)]
File:Lemonade.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4321 Lemonade (experimental)]
File:GComprisAdministration.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4314 GCompris Administration (experimental)]
File:TVRadio.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4310 TV and Radio (experimental)]
File:FreeFromMalaria.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4309 FreeFromMalaria (experimental)]
File:OpenVideoChat.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4305 Open Video Chat (experimental)]
File:MathGraph32.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4303 MathGraph32 (experimental)]
File:SonataMediaPlayer.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4301 Sonata Media Player (experimental)]
File:Wine.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4296 Wine (experimental)]
File:TetrisMat-icon.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4292 TetrisMat (experimental)]
</gallery>

== What is new for distributors and deployers ==

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.90 developer platform.

=== Widgets ===
Add ErrorAlert inherited from Alert.

=== API ===
Print warnings about the deprecated activity.info fields.

=== Dependencies ===

New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

=== Activity Authors guidelines ===
There are still many activities that do not use the new activity toolbars introduced in 0.86. We encourage the switch to use the new toolbars as there have been huge improvements in usability (e.g. stopping an activity).

Jim Simmons has written a guide to writing Sugar Activities (Please see [http://en.flossmanuals.net/ActivitiesGuideSugar/Introduction Make your own Sugar Activities!]) which details how to convert your activity to the new toolbars without compromising performance on old Sugar systems.

== What's new for packagers ==
New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

== Internationalization (i18n) and Localization (l10n) ==

== Compatibility ==
There a no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== Getting the sources ==
If you want to package sugar for your favorite distribution or just want to examine sugar's lovely code ;) you can find all the source code of each module at the links below.

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.90.1.tar.bz2 sugar 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.90.0.tar.bz2 sugar-datastore 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.90.0.tar.bz2 sugar-toolkit 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.1.tar.bz2 sugar-base 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.1.tar.bz2 sugar-presence-service 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.90.0.tar.bz2 sugar-artwork 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2388.tar.gz etoys 4.1.2388]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-118.tar.bz2 Browse 118]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-34.tar.bz2 Calculate 34]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-68.tar.bz2 Chat 68]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-98.tar.bz2 TurtleArt 98]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-20.tar.bz2 Jukebox 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-24.tar.bz2 Log 24]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-15.tar.bz2 ImageViewer 15]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-71.tar.bz2 Write 71]

== Looking at the release cycle details ==
You can browse the notes of each development release in [[{{Upcoming Stable Release}}]]. Their respective sources are listed there as well.

== Looking Forward to 0.92 ==
Introspection!

Planning of the next release cycle has started at [[0.92/Roadmap]].

== Credits ==
Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes,

* the ''maintainers'' that review patches and make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing during the development cycle a Sugar version to test with,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

0.90/Notes

2010-10-01T08:35:23Z

Bert: /* Etoys */

<noinclude>{{ Translations | [[0.90/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]
Sucrose 0.90 Release Notes

== Introduction ==
Sucrose 0.90 is the latest version of the Sugar learning environment: Sugar's focus is ease of use, stability, and first-class internationalization. Sugar is Free and Open Source Software and provides tools for learning. Furthermore, Sugar provides a flexible and powerful platform for activity developers. Sugar consists of [[Taxonomy#Glucose:_The_base_Sugar_environment|Glucose]], the base system environment; and [[Taxonomy#Fructose:_The_set_of_demonstration_activities|Fructose]], a set of demonstration activities. This new release contains many new features, performance and code improvements, bug fixes, and translations.

== What is new for users ==
=== Remove the Presence Service ===
Tomeu Vizoso from Collabora has been doing a great work to remove the [[Features/Remove_Presence_Service |Presence Service]]. There are no directly visible changes for the user but the overall collaboration experience should be more stable.

=== Sugar Ad-hoc networks ===
To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. The [[Features/Sugar_Adhoc_Networks| Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. Simon Schampijer from OLPC has been working on this Feature and back ported it as well to Sugar 0.84.

=== Enhanced color selector ===
A new [[Features/Enhanced color selector| color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. Originally proposed for 0.88 this Feature went through several design iterations and finally consensus was reached. Now, we are excited to hear what the learners think about it.

=== Spiral Home View ===
Walter Bender has been working on another Feature during this cycle. [[Features/Spiral_Home_View |The Spiral Home View]] is an enhancement to the Home View to enable the display of more icons. The idea is that after the circle becomes too large, rather than shrinking the icons, it morphs into a spiral.

=== New ordering options in the Journal ===
Andrés Ambrois has been adding [[Features/Journal_Sort | new filtering options]] to the Journal. You can order now by size, creation date and modification date. The Feature originally implemented for [[Dextrose]] and sponsored by [http://activitycentral.org activity central] has been found it's way successfully into 0.90, too.

=== New Keybindings for the Frame and Journal ===
Daniel Drake has been adding keybindings for the Journal (F5) and the Frame (F6). This will help to access those important views quicker on hardware where there is no designated key.

=== Turtle Art ===

The most visible changes are the incorporation of some new blocks, such as the 'Fill' block for created filled polygons, Gray, Black, and White blocks, and the 'Turtle Sees' block, that enables the turtle to directly interact with its canvas. There is also a [http://turtleartsite.appspot.com/ new site] for uploading and downloading Turtle Art projects.

<gallery>
File:TAMaze.png|Turtle 'sees'
File:Turtle Art Site.png|http://turtleartsite.appspot.com/
</gallery>

Please see [[0.90/TurtleArt]] for more details.

=== Etoys ===
Sugar 0.90 includes the latest Etoys release. Some of the new features in Etoys 4.1 are DrGeo, speech bubbles, a timer tile and settable preferences. Also, the QuickGuides have been translated into several languages.
<gallery>
File:Etoys41-DrGeo.png|DrGeo in Etoys
File:Etoys41-Bubble.png|Speech Bubbles
File:Etoys41-Guide.png|Translated QuickGuide
</gallery>
An important change is that projects are not saved automatically anymore when you exit the activity. Instead of the regular Stop button, you will see an Exit button:

[[File:Etoys41-Exit.png‎]]

Find out more in the [http://squeakland.org/download/releaseNotes.jsp 4.1 release notes].

=== Sugar Activities ===

While we bundle a small subset of the Sugar Activities within Sucrose, most of the Activity "activity" can be tracked by visiting [http://activities.sugarlabs.org the Sugar Activity Library].

We have recently surpassed ''3.6-million'' Sugar Activity downloads! There are ''hundreds of activities'' available for download in a variety of categories!

Thanks to '''''all''' the activity maintainers and developers'' for making this happen.

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Category !! No. of Activities
|-
|Search & discovery||36
|-
|Documents||13
|-
|News||3
|-
|Chat, mail and talk||6
|-
|Media creation||25
|-
|Programming||13
|-
|Maths & science||85
|-
|Maps & geography||5
|-
|Media players||1
|-
|Games||60
|-
|Teacher tools||107
|}

==== Recent additions ====
[http://activities.sugarlabs.org/en-US/sugar/browse/type:1/cat:all?sort=newest Recent additions] include:

<gallery>
File:DrGeo.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]
File:Pukallanapac.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]
File:ConstellationsFlashCards.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]
File:Gtranslator.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]
File:Words.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]
File:VNClauncher.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]
File:SunMoonMusicMC.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]
File:GetBooks.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]
File:StarChart.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]
File:XaoS.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]
File:TurtleArtMini.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]
File:SuperTux.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]
File:Nepohualtzintzin.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]
File:SlideruleA.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]
</gallery>

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Activity !! Description
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]||Dr. Geo is an interactive geometry activity. Dr. Geo allows one to create geometric figure plus the interactive manipulation of such figure in respect with their geometric constraints. It is usable in teaching situation with students from primary or secondary level. It is simple and effective with some unique features as scripting and Smalltalk programming.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]||A puzzle: Move the pieces until the circles are all solid circles.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]||This program teaches the constellations by means of a flash-card-like interface. The program draws a constellation and the student has to pick the correct name from a list of five possible choices.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]||A Sugarized version of the translation file editor "Gtranslator" The GTranslator activity allows to translate the po files locally. This should allow users without a permanent Internet access to translate off-line the localization files downloaded from the Pootle translation server and to contribute to the localization of Sugar to their own language.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]||A multi-lingual dictionary with speech synthesis.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]||This activity helps you broadcast your screen to another computer. It will automatically launch a VNC server (X11vnc) and display your IP address. You can then connect and view the screen of Sugar on another conmputer using any VNC client (e.g. TigerVNC, UltraVNC Viewer, RealVNC, etc).
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]||Sun-Moon Music MC - Realtime Sonic Environments for Children, Multiple MIDI Controller version. Collaborative exploration and performance encouraged. Requires 1 or more MIDI controllers. This version of Sun-Moon Music is especially designed for collaborative exploration and performance. All MIDI control devices must be set to the same channel.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]||The Get Books activity lets users search and retrieve books from a variety of sources (Internet Archive, Feedbooks, etc). It supports the OPDS protocol for book discovery.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]||This activity will display a map of the sky showing the position of the visible stars, some of the larger and brighter deep-sky objects (DSOs), the "classical" planets, the sun and the moon.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]||XaoS is an interactive fractal zoomer. It allows the user to continuously to zoom in or out of a fractal in a fluid, continuous motion. This capability makes XaoS great for exploring fractals, and it’s just plain fun!
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]||Turtle Art Mini is a simple graphical programming environment. It is modeled on the Logo programming language and it emphasized graphical expression by learners new to programming. (Turtle Art Mimi is a subset of the [http://activities.sugarlabs.org/en-US/sugar/addon/4027 Turtle Art] activity – AKA Turtle Blocks)
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]||A Sugar clone of the Super Tux game.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]||Abacus is a simple, customizable abacus activity for Sugar.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]||Sliderule is a simple, customizable slide rule activity for Sugar.
|}

==== New experimental activities ====
These are activities under development that may be of interest to Sugar users:
<gallery>
File:ProducePuzzle.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4322 Produce Puzzle (experimental)]
File:Lemonade.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4321 Lemonade (experimental)]
File:GComprisAdministration.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4314 GCompris Administration (experimental)]
File:TVRadio.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4310 TV and Radio (experimental)]
File:FreeFromMalaria.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4309 FreeFromMalaria (experimental)]
File:OpenVideoChat.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4305 Open Video Chat (experimental)]
File:MathGraph32.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4303 MathGraph32 (experimental)]
File:SonataMediaPlayer.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4301 Sonata Media Player (experimental)]
File:Wine.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4296 Wine (experimental)]
File:TetrisMat-icon.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4292 TetrisMat (experimental)]
</gallery>

== What is new for distributors and deployers ==

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.90 developer platform.

=== Widgets ===
Add ErrorAlert inherited from Alert.

=== API ===
Print warnings about the deprecated activity.info fields.

=== Dependencies ===

New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

=== Activity Authors guidelines ===
There are still many activities that do not use the new activity toolbars introduced in 0.86. We encourage the switch to use the new toolbars as there have been huge improvements in usability (e.g. stopping an activity).

Jim Simmons has written a guide to writing Sugar Activities (Please see [http://en.flossmanuals.net/ActivitiesGuideSugar/Introduction Make your own Sugar Activities!]) which details how to convert your activity to the new toolbars without compromising performance on old Sugar systems.

== What's new for packagers ==
New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

== Internationalization (i18n) and Localization (l10n) ==

== Compatibility ==
There a no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== Getting the sources ==
If you want to package sugar for your favorite distribution or just want to examine sugar's lovely code ;) you can find all the source code of each module at the links below.

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.90.1.tar.bz2 sugar 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.90.0.tar.bz2 sugar-datastore 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.90.0.tar.bz2 sugar-toolkit 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.1.tar.bz2 sugar-base 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.1.tar.bz2 sugar-presence-service 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.90.0.tar.bz2 sugar-artwork 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2388.tar.gz etoys 4.1.2388]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-118.tar.bz2 Browse 118]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-34.tar.bz2 Calculate 34]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-68.tar.bz2 Chat 68]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-98.tar.bz2 TurtleArt 98]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-20.tar.bz2 Jukebox 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-24.tar.bz2 Log 24]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-15.tar.bz2 ImageViewer 15]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-71.tar.bz2 Write 71]

== Looking at the release cycle details ==
You can browse the notes of each development release in [[{{Upcoming Stable Release}}]]. Their respective sources are listed there as well.

== Looking Forward to 0.92 ==
Introspection!

Planning of the next release cycle has started at [[0.92/Roadmap]].

== Credits ==
Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes,

* the ''maintainers'' that review patches and make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing during the development cycle a Sugar version to test with,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

File:Etoys41-Exit.png

2010-10-01T08:33:47Z

Bert: Exit button instead of Stop button in Etoys 4.1

Exit button instead of Stop button in Etoys 4.1

The Undiscoverable

2010-10-01T08:23:32Z

Bert: /* Etoys */

<noinclude>{{TOCright}}
[[Category:Help]]
</noinclude>

Some ideas are not easy to discover; the concept of guided [[discovery]], where a mentor helps point a learner in a fruitful direction, can accelerate the pace of learning. Some Sugar features are not easy to discover and while we are working to improve upon this, we provide some guides to discovery below.

Eventually, as editors have sufficient material, the official documentation at
[http://www.flossmanuals.net/ FLOSS Manuals] should be updated. (It's a wiki, too.)

'''New project''': [http://www.booki.cc/discovering-discovery/ Discovering Discovery] in the FLOSS Manuals Booki software.--[[User:Mokurai|Mokurai]] 11:44, 29 September 2010 (EDT)

No matter how well we do in making Sugar discoverable, there are necessarily some things that even a born lever-puller and button-clicker will not find easily, or will not understand fully. This page contains a list of such things, ranging from the almost but not quite obvious to the entirely opaque. We can consider whether some of these can be improved, but we know that there is a limit. So we have to alert teachers to these issues, and assist them to alert the children.

Nothing is 100% discoverable or 100% undiscoverable. There are many features of Sugar that can be discovered, without their use cases being in any way obvious. The question, then, is how to provide discovery projects where we know that a particular usage is appropriate, and include a hint on the feature in the lesson plan. In other cases, the children understand immediately what a function is for, as soon as they know it exists. In those cases, you generally don't have to show them twice.

Many things that would not be discovered by one individual before getting frustrated will be rapidly discovered by one child in the group and shared before any of the group get frustrated. In teaching science, Alan Kay calls this a "Galileo moment". Is this an an adequate standard of discoverability for software, or should features be discoverable by a child in isolation? Where they are not, we want teachers to know that, and we want to plan accordingly.

Many of the Activities would benefit from a Help feature.

We should probably create a subpage for each of these issues, or point to an existing Wiki page that has the information.

Again, all of these items should be clearly documented and even specially called out in the [http://www.flossmanuals.net/ FLOSS Manuals] Sugar and XO documents.

==Sugar UI==

* Views: Neighborhood, Friends, Home, current Activity

* Wireless mesh channels and access points

==Icon colors and user names==
:Personalized icons? Drawings? Pictures? How can kids make their own icon? It's a surprisingly big thing to est. an iconic identity for many... just look at forums where kids(and adults!) hang out.--[[User:Dennis Daniels|Dennis Daniels]] 16:13, 4 August 2009 (UTC)

==Search wireless connections and people by name==
Easier to find your friend if you recognize their icon. --[[User:Dennis Daniels|Dennis Daniels]] 16:15, 4 August 2009 (UTC)

==Right-click/hover menus==
Point to an icon and wait a second for its name to appear. Wait a bit longer for the accompanying menu to appear. Or, without having to wait, just right-click (o-button on an XO) to see the name and menu.
::Nice if view source was there too. --[[User:Dennis Daniels|Dennis Daniels]] 16:15, 4 August 2009 (UTC)

==Activities==
In home view (hotkey F3), there are buttons to switch between the view of favorites in a ring and a list of all installed Activities. Select the star by an Activity to make it a Favorite. The hover menu for a Favorite includes the option to remove it from favorites without deleting it, and also an Erase option which deletes that activity!
::For a school admin trying to keep machines uniform for the next wave of kids to descend upon the computer lab the erase key can pose problems, right? --[[User:Dennis Daniels|Dennis Daniels]] 16:08, 4 August 2009 (UTC)
* Frame: Views and Activities on top; Friends on the right; hardware on the bottom; open documents on the left.

* [[The Undiscoverable/Collaboration|Collaboration]]

* Use of Keep button: Keep places a checkpoint of the current state of your application in the Journal, including a screen shot, Activity state, and metadata. The user can rename the session from the name of the Activity to something specific to the session, and add a description and tags. Users do not agree on why and when to use Keep.

===Screen capture===
An important use case for the Keep button. How do we store just the image, without the software state? Some Activities, including Turtle Art, have a button for this purpose.
*: <Alt> + 1 captures the screen and stores a screenshot in the Journal.

===View source?===
Not fully implemented. On the menu in several applications.

:What's the hotkey to view source? Is there a hotkey to view the log for that specific acitivity?--[[User:Dennis Daniels|Dennis Daniels]] 16:10, 4 August 2009 (UTC)

* Copy and paste between activities? (Sometimes)

===How to quit an activity===
''Most'' activities have a "stop-sign" icon under the Activity Tab on the toolbar at the top of the screen. (GCompris activities have a "exit-door" icon in the toolbar on the bottom of the screen. Some other activities may have a quit menu item.) ''Every'' activity has Stop in the hover menu associated with the Activity icon in the Frame.

::Not all activities respond to the 'stop-sign' especially when there are system/activity crashes caused by bugs. How do users and teachers(!) kill _that_ activity?--[[User:Dennis Daniels|Dennis Daniels]] 16:09, 4 August 2009 (UTC)

* Start an Activity without resuming last session: Select Start from hover menu.

===Sugar-Emulator Screen Size Adjustment===
* In Terminal:
*: {{Code|sugar-emulator -i 600x500}} (fits the screen for a 10" Netbook as a window)
*: {{Code|sugar-emulator -f}} (Full Screen)
* Help for sugar-emulator
*: {{Code|sugar-emulator --help}}

* Modify the menu item Applications->Education->Sugar
*: Use 'Main Menu' utility (alacarte) or edit a separate launcher
*# [right click]->[add launcher to desktop]
*# right click on icon on desktop
*# Properties, Command:/usr/bin/sugar-emulator '''-i 832x624'''
*# Close

* Now a smaller Xephyr window will launch
** 832x624 matches the XO display proportions (Pages in Browse will mimic the layout of those on an XO.)

===Localization===
* [[The Undiscoverable/Change keyboard|Change keyboard]]

* [[The Undiscoverable/Change UI language|Change UI language]]

* [[The Undiscoverable/Fonts|Fonts]]

=== Remote collaboration ===
Using Community Jabber servers (Listings and how to change):
* [OLPC:Community_Jabber_Servers OLPC Community Jabber servers]

* [[Community Jabber servers|local display of the OLPC Community Jabber servers]]
* see Terminal listing below for how to change

==Icons==

Although there is no such thing as an intuitive icon, it is sometimes possible to use icons that relate to experience, and it is generally possible to make icons mnemonic, so that they don't have to be explained more than once. Note that the common icon for saving a file in GUIS for Linux, Mac, and Windows is the obsolete floppy disk. A billion people have learned it, so it has become almost unchangeable. We have started over in Sugar.

* File types.
* InfoSlicer

==Journal==

* The default text in each entry is the name of the Activity used to create it, or the name of a downloaded file. Users can edit this text to provide a meaningful title. The Description does not display in the main Journal view. Renamed sessions saved in the Journal show up on the right-click/hover menu for that Activity's icon in the Home view.

* Tags: Poor man's database. You can tag by topic, by project, or whatever else meets your needs.

* Searches examine the unnamed Title field, the Description, and the Tags texts. You don't have to examine entries one at a time to look for particular tags.

* Resume session: Left-click a Journal entry to start where you left off the last time. Right-click to get the list of Activities that can open this file. Save in Record, open in Paint, for example.

* Install Activities: Cannot install .xo over yum package. Delete Activity from /usr/share/sugar/activities, then download .xo from [http://activities.sugarlabs.org Activities repository]. Where is the result installed?

* Copy to and from USB stick: Drag Journal entries to USB icon.

* Copy file to Journal entry. With the appropriate file name and MIME type:
copy-to-journal tamyblock.py -m text/x-python

* When you download an image, it doesn't have a preview. Open it and close it immediately to generate one. [http://dev.sugarlabs.org/ticket/1106 Ticket #1106]
===Saving Work===

Basically, we need a Save as... functionality, not just a Save that overwrites the previous version and a clumsy Save on Exit where you have to go roundabout to start up again. All of this should be bugged as a Feature Request.

<pre>On Thu, Oct 8, 2009 at 6:42 PM, Caroline Meeks <caroline@solutiongrove.com> wrote:
> Today we worked with two groups on multiplication. They made squares with
> each side being a different multiplication problem that had the same answer.
> http://screencast.com/t/sUbiof2H
>
> We also had them reflect in their Journals about what they did.
> All of this went well.
>
> What was horrible was trying to get the right point in the project saved to
> the Journal and then navigating to the correct place to write.
> The solution I suggest is when you click the Keep button (Journal Icon) from
> an activity that the Journal reflection dialog box appears.
> Here are the problems we had.
>
> Hard to get to the Journal, no easy F# short cut.
> Hard to find the little arrow that gets you to where you can write.
> Especially since if the Frame is active, which it has to be to get to the
> Journal, the little bitty arrow you need to click is covered.
> When students did their assigned task they were eager to go back to
> exploring with Sugar and wrote over their work without it being saved, or
> using the same name as the assigned activity. This was probably the worst
> outcome because then it was like they hadn't done the assignment, they had
> nothing to show for their work and we'll want to use it later for a
> portfolio.
>
> clicking the Activity Tab to write down the name is a PITA (this one is
> fixed in .88 I think).
>
> After they reflected they wanted to immediately go back to exploring in TA
> and we had to stop them, make them change the name again. They were very
> perplexed by this because they didn't know what to name their new file
> because they hadn't done anything yet.
>
> The word "Description" is not very friendly. I like "What did you do?"
> Walter wants to expand it even further, I'm not sure about that, its pretty
> challenging for the students to type so I'm not sure we want more boxes.
> Confusion between the Keep button and the samples and the snapshot icons.
> No feedback when you click Keep so there is a tendency to click it
> repeatedly.
</pre>

==Activities==

* What version of this activity am I running? The list view in Home gives the number.
* Add and Remove Favorites. WARNING: Erase is '''not''' Remove Favorite.

===[http://wiki.laptop.org/go/Xo-get xo-get]===

The obsolete xo-get script and Activity accessed a repository of Activities for installation and updates. Use [http://Activities.sugarlabs.org/ Activities.sugarlabs.org] instead.

* [http://wiki.laptop.org/go/Xo-get#Installation_of_xo-get Script] [http://xo-get.olpc.at/xo-get.py Download]
* [http://wiki.laptop.org/go/Xo-get#Installation_of_xo-get_GUI Activity]

===Terminal===

* XO laptop keyboard sends screen the "erase" key as the ascii code NULL (back erases) and sees "fn+erase" as code DEL (forward erase)
* The entire [[The undiscoverable/Command line|command line]] repertoire plus scripting
* Documentation: man, info, apropos
* Linux file system: /, ., .., cd, pwd, mkdir, rmdir, cat, touch, rm, mount, umount, /etc/fstab
* Standard IO: >, >>, <, |
* Users and groups: root, /home, su, sudo, /etc/sudoers, sudoedit, visudo, chown
* Permissions: chmod drwxrwxrwx ugoa
* Regular expressions: [0-9][a-zA-Z]?, grep
* File globbing: *
* Editors: vi, pico. The emacs editor is not installed by default.
* copy-from-journal copy-to-journal: Journal entries are in ~/.sugar/default/datastore. Each entry has a metadata subdirectory.
* sugar-control-panel command: (aboutme/network/datetime/aboutcomputer/Frame/power/language) settings. Use this command (small L) to list available functions.
sugar-control-panel -l
* File browser: Install Midnight Commander (mc)

See FLOSS Manuals [http://en.flossmanuals.net/terminal Terminal] and [http://en.flossmanuals.net/CommandLineIntro/AboutThisManual Introduction to the GNU/Linux Command Line] for a gentle introduction to these functions and features.

===Etoys===

* It's a programming language.
* It's huge.
* The tutorials are excellent as far as they go, but they stop short.
* [[The undiscoverable/Projects|Projects]]? What are projects? How do I do that?
* Program tiles
* Make tile
* Objects
* Code viewer
* Multimedia
* Presentations
* Link: http://squeakland.org/
* Hint: to share an Object or the desktop in e-toys
:Drag over a buddy it should highlight

===Pippy===

* You can edit the programs and run the changed versions.
* You can create your own programs. Click Clear, enter a Pythonic name to replace Pippy Activity, and Keep.
* You can import libraries.
* Turtle Art has a programmable tile that holds a single Python expression.
* Turtle Art has a programmable tile that reads tamyblock.py. Right-click on it in the Journal to open it in Pippy.
* Python is a large programming language. How do I learn it?
* How do I tackle the [http://api.sugarlabs.org/ Sugar API]?
* What is the difference between Keeping as a Python file and as a bundle?

===Turtle Art===

* Color space: The image below shows the colors that the Turtle draws for inputs in the range 0-399. The range repeats after 200. The 100-199 and 300-399 ranges are the reverse of the 0-99 and 200-299 ranges.
[[File:TA_Colors.png]]
* Shades: The image below shows all color and shade combinations in the ranges 0-99.
[[File:TAShadesAndColors.png]]

===Write===

* When unformatted text is selected the Style menu appears with only one item visible: None. Unless the user notices the little up arrowhead and moves the cursor up to reveal the rest of the menu, Styles remain a mystery.
* When text is selected, and the color palette opened, clicking outside the palette window dismisses the palette. Not a problem so far. However, if the user clicks in the edit window, the previously selected text is deselected and no color applied. Clicking anywhere on the toolbar applies the color and leaves the text selected. It has been suggested in [http://www.mail-archive.com/sugar-devel@lists.sugarlabs.org/msg08918.html mailing list thread] that adding 'OK' and 'Cancel' buttons, as in the color palette in Paint, would solve this problem.

===[[The Undiscoverable/Calculate|Calculate]]===

* Graphing
* Help

===Measure===

* Frequency and amplitude settings

===Library===

* I'm sorry, what is this for? Oh, wait, is this what the Journal was supposed to be? No, it only shows one entry for each activity. I can't list individual sessions or documents. So what is it for?

===Browse===

* [[The Undiscoverable/Bookmarks|Bookmarks]]
* You can use browse to browse the file system and .py files
* Uploading from Journal
* [[wikipedia:About:config|about]]:config (Enter this in the address bar to see and set Browse configuration values, such as for [[olpc:Our software#Proxy configuration]])

===Jukebox===

* Where is the music?

===IRC===
* Change name: click on name in right bottom corner, edit, hit <enter>
* /join #''channel'' command

*How to change the autologon channels on the XoIRC application in sugar:
*in terminal enter gedit then open and edit the file ircactivity.py
in .../Activities/IRC.activity subdirectory. ( install gedit with yum install.)
*add "client.add-channel ('sugar') "lines with the different #channels
inside quotes that you want to open on startup, Then save the changed file.
Now autologon to those channels works on startup

==Programming==

We have activities for the Smalltalk, Python, and Logo languages. Etoys includes a different version of turtle graphics. We have to provide an appropriately graded curriculum on the basic concepts of programming, starting with simple actions, such as Turtle Art drawing commands. Then we have to deal with variables, subroutines, control flow, functions or methods, and so on up to object class definitions and libraries. The laptops also have FORTH and Perl installed, and we will want materials for those, starting no doubt in later grades.

We also need to bring in the Computer Science idea that the deep structure of a program is not the surface syntax, but is much more like the trees that we build in Turtle Art.

==Subject matter==

Whether in math, science, music, art, or any other subjects, there is much that cannot be discovered in unguided exploration, that has taken thousands of years of human history to achieve. The chief task in building new learning materials will be discovering ways to structure learning to maximize the amount of discovery the children can achieve, with the minimum of direction.

We also need to be clear about skills that need practice more than discovery, as in music and sports, or keyboarding or language. What is the proper balance? On this point, see Muska Mosston, The Spectrum of Teaching Styles: From Command to Discovery. Longman, 1989. ISBN 0801303508 (out of print)

==Hardware==

Sugar runs on hardware and there are some hardware specific interactions that can be difficult to discover. For example, the function keys (F1–F4) map to the Sugar zoom levels/neighborhood views. This mapping is evident on the OLPC XO-1 hardware, which has dedicated symbols on those keys, but not as easy to discover on generic keyboards. Similarly, there is a key dedicated to the Frame on the OLPC XO-1 keyboard. The Frame is accessed through a keyboard shortcut on a generic keyboard (Alt-Shift-F).

Listed below are some of the undiscoverable features specific to hardware.

===OLPC XO-1===

* Power button: In many target countries, many will not be familiar with international symbols.
* Left and right "mouse" buttons: Young children may have even more trouble with left and right than grownups. For this reason, the left button is marked 'x', and the right button, 'o'.
* Opening: The latching mechanism is a hidden part of the antennae. Readily discoverable by children, but not by all adults, some of whom have to be shown more than once. This puzzle aspect of the XO is actually beneficial in some ways.
* Position of antennae. They work better in a generally upright position, parallel to each other.
* Rotate screen button: Easy to find, but what's it for?
* Book reader mode and page controls: You also need to know about screen rotation to make this work properly.
* Keyboard switching key, replacing ×÷ on keyboards for countries and languages using a non-Latin alphabet or other kind of writing system.
* Keyboard sends screen the "erase" key as the ascii code NULL (back erase) and sees "fn+erase" as code DEL (forward erase).

====Open Firmware====

This is presently only relevant to OLPC XO hardware, which uses Open Firmware instead of a BIOS.

On an unlocked XO,

* At boot time, press and hold the escape key to get into Open Firmware.
* In the Terminal activity, execute the command

echo y > /proc/sysrq-trigger

See [[olpc:FORTH]] for a brief introduction to the FORTH programming language, which Open Firmware is written in, plus links to other resources.

Be careful with OFW. You can seriously mess up or brick your XO with it. You might want to experiment in gForth first.

==Subpages==

{{Special:PrefixIndex/{{PAGENAMEE}}/}}

0.90/Notes

2010-09-30T17:20:47Z

Bert: /* Etoys */ Added screenshots

<noinclude>{{ Translations | [[0.90/Notes|english]] }}{{TeamHeader|Development Team|home=Development Team|roadmap_link={{Upcoming Stable Release}}/Roadmap}}</noinclude>[[Category:Release Notes]]
Sucrose 0.90 Release Notes

== Introduction ==
Sucrose 0.90 is the latest version of the Sugar learning environment: Sugar's focus is ease of use, stability, and first-class internationalization. Sugar is Free and Open Source Software and provides tools for learning. Furthermore, Sugar provides a flexible and powerful platform for activity developers. Sugar consists of [[Taxonomy#Glucose:_The_base_Sugar_environment|Glucose]], the base system environment; and [[Taxonomy#Fructose:_The_set_of_demonstration_activities|Fructose]], a set of demonstration activities. This new release contains many new features, performance and code improvements, bug fixes, and translations.

== What is new for users ==
=== Remove the Presence Service ===
Tomeu Vizoso from Collabora has been doing a great work to remove the [[Features/Remove_Presence_Service |Presence Service]]. There are no directly visible changes for the user but the overall collaboration experience should be more stable.

=== Sugar Ad-hoc networks ===
To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. The [[Features/Sugar_Adhoc_Networks| Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. Simon Schampijer from OLPC has been working on this Feature and back ported it as well to Sugar 0.84.

=== Enhanced color selector ===
A new [[Features/Enhanced color selector| color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. Originally proposed for 0.88 this Feature went through several design iterations and finally consensus was reached. Now, we are excited to hear what the learners think about it.

=== Spiral Home View ===
Walter Bender has been working on another Feature during this cycle. [[Features/Spiral_Home_View |The Spiral Home View]] is an enhancement to the Home View to enable the display of more icons. The idea is that after the circle becomes too large, rather than shrinking the icons, it morphs into a spiral.

=== New ordering options in the Journal ===
Andrés Ambrois has been adding [[Features/Journal_Sort | new filtering options]] to the Journal. You can order now by size, creation date and modification date. The Feature originally implemented for [[Dextrose]] and sponsored by [http://activitycentral.org activity central] has been found it's way successfully into 0.90, too.

=== New Keybindings for the Frame and Journal ===
Daniel Drake has been adding keybindings for the Journal (F5) and the Frame (F6). This will help to access those important views quicker on hardware where there is no designated key.

=== Turtle Art ===

The most visible changes are the incorporation of some new blocks, such as the 'Fill' block for created filled polygons, Gray, Black, and White blocks, and the 'Turtle Sees' block, that enables the turtle to directly interact with its canvas. There is also a [http://turtleartsite.appspot.com/ new site] for uploading and downloading Turtle Art projects.

<gallery>
File:TAMaze.png|Turtle 'sees'
File:Turtle Art Site.png|http://turtleartsite.appspot.com/
</gallery>

Please see [[0.90/TurtleArt]] for more details.

=== Etoys ===
Sugar 0.90 includes the latest Etoys release. Some of the new features in Etoys 4.1 are DrGeo, speech bubbles, a timer tile and settable preferences. Also, the QuickGuides have been translated into several languages.
<gallery>
File:Etoys41-DrGeo.png|DrGeo in Etoys
File:Etoys41-Bubble.png|Speech Bubbles
File:Etoys41-Guide.png|Translated QuickGuide
</gallery>
Find out more in the [http://squeakland.org/download/releaseNotes.jsp 4.1 release notes].

=== Sugar Activities ===

While we bundle a small subset of the Sugar Activities within Sucrose, most of the Activity "activity" can be tracked by visiting [http://activities.sugarlabs.org the Sugar Activity Library].

We have recently surpassed ''3.6-million'' Sugar Activity downloads! There are ''hundreds of activities'' available for download in a variety of categories!

Thanks to '''''all''' the activity maintainers and developers'' for making this happen.

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Category !! No. of Activities
|-
|Search & discovery||36
|-
|Documents||13
|-
|News||3
|-
|Chat, mail and talk||6
|-
|Media creation||25
|-
|Programming||13
|-
|Maths & science||85
|-
|Maps & geography||5
|-
|Media players||1
|-
|Games||60
|-
|Teacher tools||107
|}

==== Recent additions ====
[http://activities.sugarlabs.org/en-US/sugar/browse/type:1/cat:all?sort=newest Recent additions] include:

<gallery>
File:DrGeo.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]
File:Pukallanapac.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]
File:ConstellationsFlashCards.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]
File:Gtranslator.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]
File:Words.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]
File:VNClauncher.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]
File:SunMoonMusicMC.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]
File:GetBooks.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]
File:StarChart.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]
File:XaoS.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]
File:TurtleArtMini.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]
File:SuperTux.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]
File:Nepohualtzintzin.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]
File:SlideruleA.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]
</gallery>

{| border=1 cellpadding=3 style="border: 1px solid white; border-collapse: collapse; background: #e3e4e5;"
|-style="background:#787878; color: white;"
! Activity !! Description
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4323 Dr. Geo]||Dr. Geo is an interactive geometry activity. Dr. Geo allows one to create geometric figure plus the interactive manipulation of such figure in respect with their geometric constraints. It is usable in teaching situation with students from primary or secondary level. It is simple and effective with some unique features as scripting and Smalltalk programming.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4320 Pukllanapac]||A puzzle: Move the pieces until the circles are all solid circles.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4318 Constellations Flash Cards]||This program teaches the constellations by means of a flash-card-like interface. The program draws a constellation and the student has to pick the correct name from a list of five possible choices.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4317 gtranslator]||A Sugarized version of the translation file editor "Gtranslator" The GTranslator activity allows to translate the po files locally. This should allow users without a permanent Internet access to translate off-line the localization files downloaded from the Pootle translation server and to contribute to the localization of Sugar to their own language.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4315 Words]||A multi-lingual dictionary with speech synthesis.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4311 VNC Launcher]||This activity helps you broadcast your screen to another computer. It will automatically launch a VNC server (X11vnc) and display your IP address. You can then connect and view the screen of Sugar on another conmputer using any VNC client (e.g. TigerVNC, UltraVNC Viewer, RealVNC, etc).
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4308 Sun Moon Music]||Sun-Moon Music MC - Realtime Sonic Environments for Children, Multiple MIDI Controller version. Collaborative exploration and performance encouraged. Requires 1 or more MIDI controllers. This version of Sun-Moon Music is especially designed for collaborative exploration and performance. All MIDI control devices must be set to the same channel.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4304 Get Books]||The Get Books activity lets users search and retrieve books from a variety of sources (Internet Archive, Feedbooks, etc). It supports the OPDS protocol for book discovery.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4300 Star Chart]||This activity will display a map of the sky showing the position of the visible stars, some of the larger and brighter deep-sky objects (DSOs), the "classical" planets, the sun and the moon.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4299 XaoS]||XaoS is an interactive fractal zoomer. It allows the user to continuously to zoom in or out of a fractal in a fluid, continuous motion. This capability makes XaoS great for exploring fractals, and it’s just plain fun!
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4298 Turtle Art Mini]||Turtle Art Mini is a simple graphical programming environment. It is modeled on the Logo programming language and it emphasized graphical expression by learners new to programming. (Turtle Art Mimi is a subset of the [http://activities.sugarlabs.org/en-US/sugar/addon/4027 Turtle Art] activity – AKA Turtle Blocks)
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4297 Super Tux]||A Sugar clone of the Super Tux game.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4293 Abacus]||Abacus is a simple, customizable abacus activity for Sugar.
|-
||[http://activities.sugarlabs.org/en-US/sugar/addon/4222 Slide rule]||Sliderule is a simple, customizable slide rule activity for Sugar.
|}

==== New experimental activities ====
These are activities under development that may be of interest to Sugar users:
<gallery>
File:ProducePuzzle.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4322 Produce Puzzle (experimental)]
File:Lemonade.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4321 Lemonade (experimental)]
File:GComprisAdministration.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4314 GCompris Administration (experimental)]
File:TVRadio.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4310 TV and Radio (experimental)]
File:FreeFromMalaria.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4309 FreeFromMalaria (experimental)]
File:OpenVideoChat.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4305 Open Video Chat (experimental)]
File:MathGraph32.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4303 MathGraph32 (experimental)]
File:SonataMediaPlayer.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4301 Sonata Media Player (experimental)]
File:Wine.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4296 Wine (experimental)]
File:TetrisMat-icon.png|[http://activities.sugarlabs.org/en-US/sugar/addon/4292 TetrisMat (experimental)]
</gallery>

== What is new for distributors and deployers ==

== What's new for developers ==
The following changes are important for developers using the Sucrose 0.90 developer platform.

=== Widgets ===
Add ErrorAlert inherited from Alert.

=== API ===
Print warnings about the deprecated activity.info fields.

=== Dependencies ===

New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

=== Activity Authors guidelines ===
There are still many activities that do not use the new activity toolbars introduced in 0.86. We encourage the switch to use the new toolbars as there have been huge improvements in usability (e.g. stopping an activity).

Jim Simmons has written a guide to writing Sugar Activities (Please see [http://en.flossmanuals.net/ActivitiesGuideSugar/Introduction Make your own Sugar Activities!]) which details how to convert your activity to the new toolbars without compromising performance on old Sugar systems.

== What's new for packagers ==
New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

== Internationalization (i18n) and Localization (l10n) ==

== Compatibility ==
There a no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== Getting the sources ==
If you want to package sugar for your favorite distribution or just want to examine sugar's lovely code ;) you can find all the source code of each module at the links below.

=== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.90.1.tar.bz2 sugar 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.90.0.tar.bz2 sugar-datastore 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.90.0.tar.bz2 sugar-toolkit 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.1.tar.bz2 sugar-base 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.1.tar.bz2 sugar-presence-service 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.90.0.tar.bz2 sugar-artwork 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2388.tar.gz etoys 4.1.2388]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

=== <abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> modules ===
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-118.tar.bz2 Browse 118]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-34.tar.bz2 Calculate 34]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-68.tar.bz2 Chat 68]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-98.tar.bz2 TurtleArt 98]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Jukebox/Jukebox-20.tar.bz2 Jukebox 20]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Log/Log-24.tar.bz2 Log 24]
* [http://download.sugarlabs.org/sources/sucrose/fructose/ImageViewer/ImageViewer-15.tar.bz2 ImageViewer 15]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Write/Write-71.tar.bz2 Write 71]

== Looking at the release cycle details ==
You can browse the notes of each development release in [[{{Upcoming Stable Release}}]]. Their respective sources are listed there as well.

== Looking Forward to 0.92 ==
Introspection!

Planning of the next release cycle has started at [[0.92/Roadmap]].

== Credits ==
Many people contributed to this release indirectly, including testing, documentation, translation, contributing to the Wiki, outreach to education and developer communities. On behalf of the community, we give our warmest thanks to the developers and contributors who made this Sugar release possible.

We want to especially thank:
* the [[Infrastructure_Team | ''Infrastructure team'']] which does all this great work in the background without which the development would not be possible at all,

* the ''deployments'' that provide the development team with feedback from the field,

* the [[Design_Team | ''Design team'']] which guided the design of features with UI changes or impact on the workflow,

* the [[Translation_Team | ''Translation team'']] which makes sure that Sugar is enjoyable in the local languages of our users,

* the ''developers'' that submit patches for new features and bug fixes,

* the ''maintainers'' that review patches and make sure their code is shippable and which provide packagers with new tarballs,

* the ''packagers'' which provide distributions with new Sugar packages,

* the [[Sugar_on_a_Stick | ''SoaS team'']] for providing during the development cycle a Sugar version to test with,

* the ''testers'' for finding the small and bigger issues,

* the ''release team'' and [[Development_Team | ''Development team'']] for coordinating those efforts.

File:Etoys41-Guide.png

2010-09-30T17:19:37Z

Bert: Screenshot of translated QuickGuides in Etoys 4.1

Screenshot of translated QuickGuides in Etoys 4.1

File:Etoys41-Bubble.png

2010-09-30T17:12:02Z

Bert: Screenshot of Bubbles in Etoys 4.1

Screenshot of Bubbles in Etoys 4.1

File:Etoys41-DrGeo.png

2010-09-30T17:05:44Z

Bert: Screenshot of DrGeo in Etoys 4.1

Screenshot of DrGeo in Etoys 4.1

0.90/0.89.6 Notes

2010-09-22T13:58:39Z

Bert: /* Updated */ Fix spelling of etoys

<noinclude>[[Category:Release Notes]]</noinclude>

= Sucrose 0.89.6 Release Notes =

== Announcement ==
This is our development release number 6 in the [http://wiki.sugarlabs.org/go/0.90/Roadmap 0.90 development cycle]! This is our Release candidate!

We now entered [[Development_Team/Release#Hard_Code_Freeze | Hard Code Freeze]]. When the hard code freeze is in effect, each and every code change should be approved by the release team. Only critical fixes will be considered. To request approval send mail to sugar-devel@lists.sugarlabs.org, including the patch and a detailed description of the changes, the benefits and the risks. Approval will have to be granted by two members of the team.

Thanks everyone for your great contributions!

== Compatibility ==
There are no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> (base) modules==

===Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.89.4.tar.bz2 sugar-datastore 0.89.4]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2387.tar.gz etoys 4.1.2387]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.89.10.tar.bz2 sugar 0.89.10]

===Not Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.89.5.tar.bz2 sugar-toolkit 0.89.5]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.0.tar.bz2 sugar-base 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.1.tar.bz2 sugar-presence-service 0.90.1]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.89.4.tar.bz2 sugar-artwork 0.89.4]

== Glucose news ==
=== sugar ===
* Pass the contact-id to the buddy-removed signal instead of the handle {{Bug|2349}} (Tomeu Vizoso)
* Make sure we don't change the owner's colors because of a network event {{Bug|2348}} (Tomeu Vizoso)
* Commit from Sugar Labs: Translation System by user mschlager.: 361 of 363 messages translated (0 fuzzy). (Markus Schlager)
* Properly store and load friends {{Bug|2331}} (Tomeu Vizoso)
* Announce file transfer capabilities {{Bug|1603}} (Tomeu Vizoso)
* Reset resolver cache when connection has been established {{Bug|1940}} (Simon Schampijer)
* Display changed to 'Sugar in a window' instead of 'Xephyr on' Ticket {{Bug|2285}} (Ishan Bansal)
* Protected Activities Support {{Bug|2087}} (Martin Abente)
* Increase timeout for buddy properties queries {{Bug|2298}} (Tomeu Vizoso)
* Set param-register to False after a RegistrationExists error {{Bug|2296}} (Tomeu Vizoso)
* Change owner's jid to be hashed_pubkey@server {{Bug|2279}} (Tomeu Vizoso)

=== sugar-datastore ===
* metadata-only update sets filesize property to 0 {{Bug|2229}}
* commit 3644fac reintroduced race condition, broke test suite {{Bug|2104}}
* autogen.sh: pass --enable-maintainer-mode to configure

=== Etoys ===
* fix Journal saving fails in Sugar 0.82
* updated translations: de, ja, ta
* fix error when adding variable named 'val'
* fix tile help balloons not being translated
* add button to reset saved preferences
* make soundReverb a preference
* do not hard-code squeak vm path
* replace == with = in shell tests
* fix paintbox in event theatre
* fix SuppliesPlayersTool guide
* remove MenuMakeNewFlap guide from index
* pop-up arrows now enabled by default
* new DrGeo examples project (see gallery)
* new home project (green border more visible)
* Demon Castle renamed to Etoys Castle and fixed
* revised guides for English and Spanish
* DrGeoII translations for de,es,fr,ja
* updated German and Japanese translations
* do not ship languages with too few translations (ar_SY, en_GB, km, pap, pl, zh_TW)
* hide distracting/not-functional preference panel buttons
* allow negative timer values
* shared flaps are not destroyed anymore when switching projects
* various smaller fixes

==<abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> (base activity) modules==
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-117.tar.bz2 Browse 117]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-32.tar.bz2 Calculate 32]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Chat/Chat-67.tar.bz2 Chat 67]
* [http://download.sugarlabs.org/sources/sucrose/fructose/TurtleArt/TurtleArt-98.tar.bz2 TurtleArt 98]

==Fructose news==
=== Chat ===
* Remove access to a private member of the presence service (Tomeu Vizoso)

=== TurtleBlocks ===
====98====
* fixed palette selection bug introduced by alpha-value checking

====97====
* recenter default turtle when dragged onto palette
* removed comment label from collapsible stacks
* made font smaller on the bottom-of-collapsible-stack block (#2305)
* rgs fixed resume problem in GNOME version (#2293)
* checking alpha value to block 'hit' detection (#1852)
* trap and display math errors in python block (#2313)

====96====
* fixed deleted-turtle ghost bug

====95====
* some performance enhancements (block creation and stack dragging)
* removed depreciated field from desktop file (Luke Farone)
* fixed problem with setup.py in non-Sugar environments (Luke Farone)
* new example program for turtle sees block
* fixed broken clock example
* catch import error for upload (#2194)
* rescaling of read pixel values (#2188)
* turtle sees block takes into account gray and shade (#2188)
* hide extra turtles on clean (#2191)
* hide coordinate overlays on clean (#2191)
* reset scale, gray on clean (#2191)
* work-around to c-c/c-v toolbar bug (Raul Gutierrez #2050)
* writing config file in config directory (Luke Farone #2193)
* using turtle name to generate color for multiple turtles
* delete turtle when dragged onto the palette (#2191)

====94====
* added "turtle sees" block
* added read_pixel block
* updated sample images (smaller file sizes)
* updated license for sample images
* updated nl translation
* fixed path problem with Exec in desktop file (Matthew Gallagher)
* fixed path problem with icon in turtleart.py (Matthew Gallagher)
* moved modules to TurtleArt subdirectory
* limit size of upload file (Jamie Boisture)

====93====
* recenter overlays when window resizes (Jamie Boisture)
* added icon for Desktop mode (Jamie Boisture)
* support for project upload to server for Desktop mode (Jamie Boisture)

====92====
* fixed sharing bug introduced in v91
* cleaned up cmdline processing

====91====
* added black and white blocks
* fixed cgi escape bug (#1854)
* fixed bug with overzealous block resizing (#2092)
* speed up of refresh code (expose_cb handling)

====90====
* fixed problem with keyboard accelerators: Ctrl-C, Ctrl-V, and Alt-Return

====89====
* added non-interactive mode (with help from Jamie Boisture)
* fix problem with icon in F13
* block scale saved between sessions

====88====
* alsroot fixed ObjectChooser bug (#2002)

====87====
* added fill block
* added gray block
* fixed typo in sample code
* added mouse support to sample code (See
http://tonyforster.blogspot.com/2010/03/mouse-support-in-turtleart.html)

====86====
* More .es updates

====85====
* Fixed bug loading floating point numbers from saved projects
* 'store in box' accepts strings and numbers as labels
* New .es translations

== What is new for packagers ==
New API has been added to telepathy-gabble and telepathy-salut to support the work on the collaboration framework, which results in needing 0.9.16 for tp-gabble and 0.3.13 for tp-salut.

One of the goals of the collaboration refactoring was dropping functionality in sugar that has been implemented in [http://telepathy.freedesktop.org/wiki/Mission%20Control telepathy-mission-control], so Sugar now depends on tp-mission-control 5.4.3.

Collaboration

2010-09-03T13:31:09Z

Bert: /* Testing */ unset XAUTHORITY

<noinclude>{{ GoogleTrans-en | es =show | bg =show | zh-CN =show | zh-TW =show | hr =show | cs =show | da =show | nl =show | fi =show | fr =show | de =show | el =show | hi =show | it =show | ja =show | ko =show | no =show | pl =show | pt =show | ro =show | ru =show | sv =show }}
</noinclude>
{{TOCright}}

== Parents and kids ==
Collaboration in the Sugar sense is simply helping kids play together. Kids play together all the time. They talk, they run, they throw balls back and forth. Sugar allows kids to talk and play and learn together.

'''Activities''' - Activities, in the Sugar world, are the programs and applications on which kids learn.

'''Neighborhood''' - Kids find people to play with in their neighborhood view. Who will be in my kids neighborhood?

Really, that is all you need to know when everything works.

But sometimes there are problems.

== Technologists==
(School/Camp IT person, Tech Savvy Teacher, and others)

There are two routes for collaboration.

# You can collaborate "locally" without a server. If you remove the name of the Jabber server from your settings, or it fails to connect for some reason, then Sugar tries to connect locally. Sugar machines will be able to collaborate if they are connected to the same wireless network or wired port. It will not work over your entire LAN, you have to be on the same segment.
# You connect up to a Jabber Server. You can either use one on the Internet or you can install your own as part of an XS server installation. To use a Jabber server, go to 'My Settings' -> Network and put in the name of the server you want to use.
===Local Collaboration on a Wired Network===

To turn on local collaboration go to 'My Settings' -> Network and remove the server name. A blank setting will enable local collaboration.

In many situations, computers in the same computer lab will automatically find each other.

Bug {{Bug|1113}} is an example of a situation where this didn't work. Can we give people some guidance on how to make local collaboration work?
==Poet's Guide to Collaboration ==

----------------------------------------------
|
| Activities
|
----------------------------------------------
|
| Presence Service
|
----------------------------------------------
|
| D- bus
|
----------------------------------------------
|
| Telepathy
|
----------------------------------------------
|
| Telepathy-gabble
|
----------------------------------------------
|
| XMPP
|
-----------------------------------------------
|
| Jabber Server
|
----------------------------------------------

=== Activity Developers ===

'''Presence Service''' - The Presence Service is a set of APIs which allow developers to enable collaboration features on Sugar.

That is all you need to know. The rest is under the covers.

=== Core Sugar Developers ===

'''Telepathy''' - Telepathy is another set of APIs which has a 'plug-in' design so that various communication protocols can be 'plugged-in' without affecting what the user of activity developers sees.

=== Collaboration Developers ===

'''Telepathy-gabble''' - Telepathy-gabble is a plug-in backend that uses the XMPP protocol to talk to a server.

'''XMPP''' - Extensible Messaging and Presence Protocol ([[wikipedia:XMPP|XMPP]]) is an open, XML-based protocol originally aimed at near-real-time, extensible instant messaging (IM) and presence information. (buddy lists)

'''XMPP Server''' - At the bottom to the stack is a XMPP server. These are often referred to as jabber servers because the first popular XMPP Server was called jabberd.

== Testing ==

To test collaboration using a single development system, you can run multiple Sugar instances on the
same machine:

* Create a test user

user$ sudo useradd -m test1

* Become the test user. If $DISPLAY is not preserved, you may have to set it manually. And you may have to unset XAUTHORITY.

user$ sudo -i -u test1
test1$ export DISPLAY=:0
test1$ unset XAUTHORITY

* Copy-paste the output of "xauth list" ran from your regular account

test1$ xauth add giskard.codewiz.org/unix:0 MIT-MAGIC-COOKIE-1 9be6c305b20ee7803a7280da553f170e

* This requires your home to be world-accessible

test1$ cd ~user/src/sugar/sugar-jhbuild
test1$ ./sugar-jhbuild run sugar-emulator

* Repeat the above procedure as many time as desired to test N-way collaboration

==See also==
* [[OLPC:Collaboration Central]]
* [[OLPC:Activity sharing]]
* [[OLPC:Tubes]]

[[Category:Collaboration]]

0.90/0.89.3 Notes

2010-08-20T20:13:11Z

Bert: /* Glucose news */

<noinclude>[[Category:Release Notes]]</noinclude>

= Sucrose 0.89.3 Release Notes =

== Announcement ==
This is our third release in the [http://wiki.sugarlabs.org/go/0.90/Roadmap 0.90 development cycle]!

We now reached Feature Freeze! We are glad to announce that two Features have been pushed already.

A [[Features/Enhanced_color_selector | new color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. We already wanted to land the Feature in 0.88 but had so many ideas that we did not reach consensus in the end. Now, we are excited to hear what the learners think about it.

To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. [[Features/Sugar_Adhoc_Networks |The Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. If Sugar sees no "known" network (the learner has not been connected to an currently available Access Point before) when it starts, it does autoconnect to an Ad-hoc network. First we try if there is an Ad-hoc network that is used by other learners in the area, if not we default to channel 1.

Another great Feature will be available in 0.89.4. [[Features/Remove_Presence_Service |This Feature]] removes the need for the Presence Service, meaning that activities and the Shell need to interact directly with non-Sugar-specific services such as Telepathy. As it touches three modules reviewing took a few more days. Since it is the mayor 0.90 Feature we gave it a deadline exception. The code has been pushed as I am writing these lines...

Thanks everyone for your great contributions!

== Compatibility ==
There are no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> (base) modules==

===Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.89.3.tar.bz2 sugar 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.89.3.tar.bz2 sugar-artwork 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.89.3.tar.bz2 sugar-toolkit 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.0.tar.bz2 sugar-presence-service 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.0.tar.bz2 sugar-base 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2382.tar.gz etoys 4.1.2382]

===Not Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.89.2.tar.bz2 sugar-datastore 0.89.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

== Glucose news ==
=== sugar ===
* Repair for file transfers (Tomeu Vizoso)
* Journal: show error message on write failure {{Bug|1842}} (Anish Mangal)
* Restore sugar-launch by bundle id substring {{Bug|897}} (James Cameron)
* Add default Ad-hoc networks {{Bug|1610}} (Simon Schampijer)
* Fixed text overflow in About my Computer CP section {{Bug|1980}} (Tim McNamara)
* Added enhanced color selector: cycle through previous and next stroke and fill colors instead of random (Walter Bender)
* Add touchpad device to Frame for switching between capacitive and resistive modes (Walter Bender)

===sugar-artwork===
* Alternative to Create a new wireless network. {{Bug|1610}} (Simon Schampijer)

=== sugar-toolkit ===
* Print warnings about the deprecated activity.info fields (Simon Schampijer)
* Add ErrorAlert inherited from Alert (Anish Mangal)

=== sugar-presence-service ===
* bump version number

=== sugar-base ===
* bump version number

=== etoys ===
* switched to etoys.squeak.org/svn repo
* translations broken up in smaller files
* activity version will not track etoys version anymore
* QuickGuides translated to Spanish, Portuguese, German, Italian, and (some) French
* added DrGeo for exploring geometry
* sketches support flipping
* geometry tiles for the world
* timer tile (world and other playfields)
* can store preferences
* plus bug fixes

==<abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> (base activity) modules==
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-117.tar.bz2 Browse 117]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-32.tar.bz2 Calculate 32]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]

==Fructose news==
No news.

== What is new for packagers ==
Nothing new as of today.

0.90/0.89.3 Notes

2010-08-20T20:11:50Z

Bert: /* Fructose (base activity) modules */

<noinclude>[[Category:Release Notes]]</noinclude>

= Sucrose 0.89.3 Release Notes =

== Announcement ==
This is our third release in the [http://wiki.sugarlabs.org/go/0.90/Roadmap 0.90 development cycle]!

We now reached Feature Freeze! We are glad to announce that two Features have been pushed already.

A [[Features/Enhanced_color_selector | new color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. We already wanted to land the Feature in 0.88 but had so many ideas that we did not reach consensus in the end. Now, we are excited to hear what the learners think about it.

To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. [[Features/Sugar_Adhoc_Networks |The Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. If Sugar sees no "known" network (the learner has not been connected to an currently available Access Point before) when it starts, it does autoconnect to an Ad-hoc network. First we try if there is an Ad-hoc network that is used by other learners in the area, if not we default to channel 1.

Another great Feature will be available in 0.89.4. [[Features/Remove_Presence_Service |This Feature]] removes the need for the Presence Service, meaning that activities and the Shell need to interact directly with non-Sugar-specific services such as Telepathy. As it touches three modules reviewing took a few more days. Since it is the mayor 0.90 Feature we gave it a deadline exception. The code has been pushed as I am writing these lines...

Thanks everyone for your great contributions!

== Compatibility ==
There are no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> (base) modules==

===Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.89.3.tar.bz2 sugar 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.89.3.tar.bz2 sugar-artwork 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.89.3.tar.bz2 sugar-toolkit 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.0.tar.bz2 sugar-presence-service 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.0.tar.bz2 sugar-base 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2382.tar.gz etoys 4.1.2382]

===Not Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.89.2.tar.bz2 sugar-datastore 0.89.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

== Glucose news ==
=== sugar ===
* Repair for file transfers (Tomeu Vizoso)
* Journal: show error message on write failure {{Bug|1842}} (Anish Mangal)
* Restore sugar-launch by bundle id substring {{Bug|897}} (James Cameron)
* Add default Ad-hoc networks {{Bug|1610}} (Simon Schampijer)
* Fixed text overflow in About my Computer CP section {{Bug|1980}} (Tim McNamara)
* Added enhanced color selector: cycle through previous and next stroke and fill colors instead of random (Walter Bender)
* Add touchpad device to Frame for switching between capacitive and resistive modes (Walter Bender)

===sugar-artwork===
* Alternative to Create a new wireless network. {{Bug|1610}} (Simon Schampijer)

=== sugar-toolkit ===
* Print warnings about the deprecated activity.info fields (Simon Schampijer)
* Add ErrorAlert inherited from Alert (Anish Mangal)

=== sugar-presence-service ===
* bump version number

=== sugar-base ===
* bump version number

=== etoys ===
* fix DBus service methods
* fix NavBar not showing Sugar buttons
* fix 'length' and 'width' being read-only
* flip commands renamed to 'flip left right' and 'flip up down'
* fix QuickGuides showing up twice

==== Changes since 4.0 ====
* switched to etoys.squeak.org/svn repo
* translations broken up in smaller files
* activity version will not track etoys version anymore
* QuickGuides translated to Spanish, Portuguese, German, Italian, and (some) French
* added DrGeo for exploring geometry
* sketches support flipping
* geometry tiles for the world
* timer tile (world and other playfields)
* can store preferences
* plus bug fixes

==<abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> (base activity) modules==
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-117.tar.bz2 Browse 117]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-32.tar.bz2 Calculate 32]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Etoys/Etoys-116.tar.gz Etoys 116]

==Fructose news==
No news.

== What is new for packagers ==
Nothing new as of today.

0.90/0.89.3 Notes

2010-08-20T20:11:26Z

Bert: /* Updated */

<noinclude>[[Category:Release Notes]]</noinclude>

= Sucrose 0.89.3 Release Notes =

== Announcement ==
This is our third release in the [http://wiki.sugarlabs.org/go/0.90/Roadmap 0.90 development cycle]!

We now reached Feature Freeze! We are glad to announce that two Features have been pushed already.

A [[Features/Enhanced_color_selector | new color selector]] is available for the control panel, thanks to the ongoing efforts of Walter Bender and the design team. We already wanted to land the Feature in 0.88 but had so many ideas that we did not reach consensus in the end. Now, we are excited to hear what the learners think about it.

To mimic the mesh behavior on devices where mesh hardware is not available and make the "under a tree"-scenario possible the Sugar Ad-hoc networks have been added. [[Features/Sugar_Adhoc_Networks |The Feature]] will add three default Ad-hoc networks, for channel 1, 6 and 11. They will be represented with designated icons in the neighborhood view. If Sugar sees no "known" network (the learner has not been connected to an currently available Access Point before) when it starts, it does autoconnect to an Ad-hoc network. First we try if there is an Ad-hoc network that is used by other learners in the area, if not we default to channel 1.

Another great Feature will be available in 0.89.4. [[Features/Remove_Presence_Service |This Feature]] removes the need for the Presence Service, meaning that activities and the Shell need to interact directly with non-Sugar-specific services such as Telepathy. As it touches three modules reviewing took a few more days. Since it is the mayor 0.90 Feature we gave it a deadline exception. The code has been pushed as I am writing these lines...

Thanks everyone for your great contributions!

== Compatibility ==
There are no known compatibility issues, as of today.

== Update to this version ==
Please use the instructions for your distribution (SoaS, Fedora, Ubuntu, Debian etc) of choice to upgrade to this release. Note that it may take a while until the release is packaged for each distribution. Please stay tuned for distribution specific announcements and watch out for updates at [[Downloads|Get Sugar]].

== <abbr title="Glucose, the base Sugar environment">Glucose</abbr> (base) modules==

===Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar/sugar-0.89.3.tar.bz2 sugar 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-artwork/sugar-artwork-0.89.3.tar.bz2 sugar-artwork 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-toolkit/sugar-toolkit-0.89.3.tar.bz2 sugar-toolkit 0.89.3]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-presence-service/sugar-presence-service-0.90.0.tar.bz2 sugar-presence-service 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-base/sugar-base-0.90.0.tar.bz2 sugar-base 0.90.0]
* [http://download.sugarlabs.org/sources/sucrose/glucose/etoys/etoys-4.1.2382.tar.gz etoys 4.1.2382]

===Not Updated===
* [http://download.sugarlabs.org/sources/sucrose/glucose/sugar-datastore/sugar-datastore-0.89.2.tar.bz2 sugar-datastore 0.89.2]
* [http://download.sugarlabs.org/sources/sucrose/glucose/hulahop/hulahop-0.7.1.tar.bz2 hulahop 0.7.1]

== Glucose news ==
=== sugar ===
* Repair for file transfers (Tomeu Vizoso)
* Journal: show error message on write failure {{Bug|1842}} (Anish Mangal)
* Restore sugar-launch by bundle id substring {{Bug|897}} (James Cameron)
* Add default Ad-hoc networks {{Bug|1610}} (Simon Schampijer)
* Fixed text overflow in About my Computer CP section {{Bug|1980}} (Tim McNamara)
* Added enhanced color selector: cycle through previous and next stroke and fill colors instead of random (Walter Bender)
* Add touchpad device to Frame for switching between capacitive and resistive modes (Walter Bender)

===sugar-artwork===
* Alternative to Create a new wireless network. {{Bug|1610}} (Simon Schampijer)

=== sugar-toolkit ===
* Print warnings about the deprecated activity.info fields (Simon Schampijer)
* Add ErrorAlert inherited from Alert (Anish Mangal)

=== sugar-presence-service ===
* bump version number

=== sugar-base ===
* bump version number

=== etoys ===
* fix DBus service methods
* fix NavBar not showing Sugar buttons
* fix 'length' and 'width' being read-only
* flip commands renamed to 'flip left right' and 'flip up down'
* fix QuickGuides showing up twice

==== Changes since 4.0 ====
* switched to etoys.squeak.org/svn repo
* translations broken up in smaller files
* activity version will not track etoys version anymore
* QuickGuides translated to Spanish, Portuguese, German, Italian, and (some) French
* added DrGeo for exploring geometry
* sketches support flipping
* geometry tiles for the world
* timer tile (world and other playfields)
* can store preferences
* plus bug fixes

==<abbr title="Fructose, the base set of demonstration activities">Fructose</abbr> (base activity) modules==
* [http://download.sugarlabs.org/sources/sucrose/fructose/Pippy/Pippy-37.tar.bz2 Pippy 37]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Browse/Browse-117.tar.bz2 Browse 117]
* [http://download.sugarlabs.org/sources/sucrose/fructose/Calculate/Calculate-32.tar.bz2 Calculate 32]

==Fructose news==
No news.

== What is new for packagers ==
Nothing new as of today.