API reference

  For Developers

<< Developers/Documentation

This page describes the components of the XO software environment. For the low-level API available to non-Python activities, see the Low-level Activity API page.

The OLPC platform includes a large number of libraries and services. This page attempts to gather links to reference works which can be used when programming the XO laptops. This reference is primarily intended for Software Developers. You may want to try out a few Tutorials before diving into these documents.

API Changes

• Documented API changes between OLPC XO sofware releases

Platform

• Sugar Architecture
• Human interaction guidelines (HIG) for Sugar activities
• Activity Bundles describes the packaging structure
• Understanding sugar code provides an overview of how Sugar interacts with activities, including startup and shutdown, useful to understand the environment in which your activity will run
• Bitfrost summary (full spec) the security system which will control activities and their interaction with the system and other users

• Software components is a somewhat old document describing the various pieces of software and libraries involved in the system.

Sugar Specs

Documentation describing how to integrate into the Sugar GUI shell:

• Sugar almanac -- API reference
• Bundles -- general reference for OLPC bundles (including content)
  • Activity bundles -- references to Sugar's Activity (code) bundle (.xo) file format/project structure
  • Activity mimetypes -- how to specify that your activity handles a given MIME-type
• Low-level Activity API -- reference to the messages your activity should send/receive for Sugar integration

Python Libraries

Where official reference documentation isn't available, PyDoc-generated documentation is provided:

• See api.sugarlabs.org for an online version for Sugar, generated off the latest code, or
• See below for instructions on how to produce the PyDoc documentation in your own running image, for every Python package - not only Sugar.

GUI Libraries

Libraries for creating standard Windows-Icon-Menu-Pointer (WIMP) GUI applications.

• Sugar Architecture (PyDoc) -- core UI and service libraries
  • Activity Support -- support mechanisms for writing activities
  • Datastore -- activity's interface to the datastore service
    • Example -- usage of the datastore API in the Web activity's download manager
  • Code Snippets -- short fragments of code describing the canonical way to achieve various effects
  • Chat -- not widely used
  • P2P-- activity's interfaces to the Telepathy engine
  • Graphics API (PyDoc) -- UI library based on Hippo Canvas
    • Note: this API is largely deprecated, please use standard GTK operations
  • Hippo Canvas -- canvas mechanism used by the Sugar.graphics libraries
    • Note: this API is largely deprecated, please use standard GTK operations
  • Clipboard -- activity's interface to the UI's clipboard interface
    • Note: this API is not necessary for most activities, the standard GTK clipboard can be used instead
• Gtk, (PyDoc) -- GUI library underlying the Sugar UI (C API)
  • Accessibility Toolkit (ATK) (PyDoc) -- tools for providing accessible interfaces ([http://library.gnome.org/devel/atk/unstable/index.html C API)
  • GObject (PyDoc) -- non-GUI core library
  • Pango (PyDoc) -- text layout and rendering engine
    • Example -- example of using Pango to render into a GTK buffer (and from there a Pygame surface)
• Cairo (PyDoc) -- Low-level vector graphics rendering library
  • Example -- rendering of a game via Cairo
  • RSVG -- Library for rendering SVG text from files/strings onto Cairo Canvases
    • Example -- renders an SVG file to a pygame sprite
    • Example -- rendering an SVG image to a GTK surface

High-Level Widgets

GUI (GTK) controls which expose the functionality of entire complex applications for use by other projects.

• Abiword (PyDoc) -- GTK widget embedding the Abiword Word-Processor
  • Example the Write activity
• HulaHop -- embeds a Gecko 1.9 (Firefox 3.0 core) rendering widget
  • Example -- the browser module from the Web activity
• Evince -- PDF (and similar) document viewer as a GTK widget
  • Example -- the Read activity
• VteTerminal (C API) -- terminal widget
  • Example -- the Terminal activity
  • blog entry describing the widget
• GtkSourceView (C API) -- control provide source-code editing with syntax highlighting
  • Example -- the Pippy activity
  • GtkSourceView home page

Multimedia Libraries

Libraries that deal with multimedia and gaming functionality.

• GStreamer (PyDoc) -- multimedia streaming library
  • Example -- PenguinTV's gstreamer-based audio-visual control
  • Example -- Sugar's initial training/introduction video
• CSound -- the CSound audio-generation library
  • Example -- using CSound to create an audio system-load monitor application
  • Pippy's Sound Module -- play .wav and .csd files via CSound
• OLPCGames (PyDoc) -- PyGame wrapper that makes working within the OLPC-XO environment relatively straightforward (Strongly recommended for PyGame usage on the XO!)
  • Game development HOWTO -- tutorial with multiple samples (e.g. camera, video overlay, multi-channel sound, csound)
• PyGame -- GUI library suitable for Sprite-based 2D game development (usable from Pippy or OLPCGames)

Communications and Networking

Libraries for connecting to other processes, either on the local machine or across the network

• Sugar Presence API to interact with Presence Service which in turn uses Telepathy
  • Activity sharing -- includes some minimalist code on how to use Presence Service in your activities
  • Example -- HelloMesh example activity using D-Bus Tubes, documented in Collaboration Tutorial
  • Example -- example of using the Presence service in the Web activity
  • SharedState -- project to create a shared-object model over telepathy (used by Calculate)
  • Example -- the Chat activity uses Telepathy text channels
  • Example -- the Connect activity uses DBUS Tube connections
  • Example -- the Read activity opens an HTTP server running on a StreamTube to share files
  • Example -- Games/Productive uses an ExportedGObject shared over the same tube as OLPCGames.mesh
  • Example Example -- the NewsReader activity shares the current feed with joined members via an ExportedGObject (second link)
  • Example -- the Web Browser activity shares the current URL
  • Example -- the Write activity shares an instance of its core control's AbiCollab interface across a Tube
  • Example -- the OLPCGames mesh wrapper provides an example of how to use raw Tubes in a (Pygame) application, the complication being that it has to package incoming events as Pygame events.
    • Example -- use of OLPCGames.mesh to create a "Game Lobby" interface for configuring a game to be played
  • Examples -- the Telepathy-python example code (non-OLPC-specific)
• PyXPCOM -- Library for controlling XPCOM applications (currently just XULRunner on the XO) XXX Should be available, but doesn't appear to be (that is, import xpcom doesn't work)

Support Libraries

Libraries which are neither GUI nor multi-media (necessarily)

• Python Standard Modules -- modules which come with the Python language
• Xapian -- Full-Text Search library
  • Example -- the datastore uses Xapian for full-text searches
  • SECore -- search engine implementation
• JSON -- Javascript Object Notation parser/linearisation library
  • Example -- Web activity that uses JSON for some internal storage
• UrlGrabber -- url downloading library
• OLPC -- the data-store implementation
• Unicode -- the laptop must provide internationalized software, as a result you will need to use Python's Unicode support

Extraneous Libraries

Libraries which are present in the current builds, but not particularly "part" of the Sugar environment and which may be removed eventually.

• Yum -- package manager for RPM-based distributions
• RPM -- RPM manipulation library

Building PyDoc Documentation

If you just want access to the PyDoc documentation yourself, you do not need to build the documentation. You can simply start a Terminal window and run the pydoc script like so:

pydoc -p 8080

Then start a Web Browser activity and go to the URL:

http://localhost:8080

to browse all of the Python packages which are available by default on your machine.

If you really do want to create documentation for uploading to a web-site or the like, you can do the following...

In a new emulator image (you likely don't want to do this on a real OLPC as it will fill up your flash ram). Start a developer's console, then do the following:

Change to the root account (to allow for installing software with yum):

su 
yum install bzr
exit

that will download and install the bzr and python-crypto packages (about 4.8 MB) after asking you to verify that you want to do it (it will also download the yum updates, which should be small if you are using a recent emulator image).

Now, as your regular user (olpc), in the same developer's console, download the script to produce the PyDoc documentation:

bzr branch  http://www.vrplumber.com/bzr/autodoc
cd autodoc
./builddocs.py

the documentation-building process will run for a short while and produce a very large number of reasonably large HTML files in the autodoc folder.

Building epydoc Documentation

Another option is building full-system documentation like that at http://dev.laptop.org/~cscott/joyride-api/

The epydoc documentation configuration can be found at http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.py and http://dev.laptop.org/~cscott/joyride-2083-api/epydoc.config

Smalltalk Libraries

• EToys

D-BUS Services

• D-BUS (PyDoc) -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
• Presence Service -- buddy discovery and activity collaboration layer on top of Telepathy
• Telepathy Spec (PyDoc) -- buddy and connection management including cross-machine RPC over D-BUS
  • Telepathy Connection Manager
  • Telepathy StreamEngine
• Avahi -- local service discovery, e.g. for finding particular services provided on the mesh network
• NetworkManager -- network management service
• Hardware Abstraction Layer Daemon (hald) -- control of standard hardware functionality
• Activity DBus API -- Describes the API an activity must implement on D-BUS in order to interact with the Sugar desktop
  • Activity Service (Python implementation of the Activity DBus API)
• Data Store Service (Journal) -- the core data-storage operation of the laptop
• Clipboard Service -- manages cross-activity sharing of data and files
• Hardware Manager Service -- provides access to the OLPC-specific hardware on the laptop
• Activity Registry Service -- registry of installed activity bundles on the laptop
• Object Type Registry Service -- MIME-type registry service
• Sugar Console Service

System Services/Hardware

• Open Firmware/Forth -- bios-replacement system on the laptop
  • Forth Lessons -- Series of tutorial-style lessons on the Forth language and Open Firmware in particular
  • Open Firmware Quick Reference
• Hardware specification -- general description of the hardware on the laptops
  • DCON -- the display controller ASIC and its interface (note that normally you would use the HardwareManager D-BUS interface to manipulate the DCON)
  • Geode -- the Geode CPU (assembly-language optimization guide, links to data-sheets)
  • Power Domains -- description of which parts of the hardware are kept live in what situations
• Kernel
  • Rebuilding OLPC kernel -- describes how to rebuild the OLPC kernel, which is sometimes necessary if you need to support otherwise unsupported hardware

See Also

• Developers/Stack -- Developer's Manual discussion of the various operating stacks available to software developers
• Sugar Architecture -- overall discussion of the architecture (a bit dated)
  • Sugar Architecture/API -- again, a bit dated as a reference
• Graphics API -- older document describing the sugar.graphics codebase, which is now largely deprecated