API reference: Difference between revisions

From OLPC
Jump to navigation Jump to search
(→‎GUI Libraries: Added HelloMesh example for Presence)
(remove spam)
 
(12 intermediate revisions by 6 users not shown)
Line 5: Line 5:


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 [[Developers|Software Developers]]. You may want to try out a few [[Tutorials]] before diving into these documents.
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 [[Developers|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 =
= Platform =


* [[Sugar Architecture]]
* [[HIG|Human interaction guidelines (HIG)]] for Sugar activities
* [[HIG|Human interaction guidelines (HIG)]] for Sugar activities
* [[Activity Bundles]] describes the packaging structure
* [[Activity Bundles]] describes the packaging structure
Line 19: Line 24:
Documentation describing how to integrate into the [[Sugar]] GUI shell:
Documentation describing how to integrate into the [[Sugar]] GUI shell:


* [[Sugar almanac]] -- API reference
* [[Bundles]] -- general reference for OLPC bundles (including content)
* [[Bundles]] -- general reference for OLPC bundles (including content)
** [[Activity bundles]] -- references to Sugar's Activity (code) bundle (.xo) file format/project structure
** [[Activity bundles]] -- references to Sugar's Activity (code) bundle (.xo) file format/project structure
Line 26: Line 32:
= Python Libraries =
= Python Libraries =


Where official reference documentation isn't available, PyDoc-generated documentation is provided. See below for instructions on how to produce the PyDoc documentation in your own running image.
Where official reference documentation isn't available, PyDoc-generated documentation is provided:

* See [http://api.sugarlabs.org/ api.sugarlabs.org] for an online version for Sugar, generated off the latest code, or
* See [[API reference#Building PyDoc Documentation|below]] for instructions on how to produce the PyDoc documentation in your own running image, for every Python package - not only Sugar.


== GUI Libraries ==
== GUI Libraries ==
Line 34: Line 43:
* [[Sugar Architecture]] [http://www.vrplumber.com/sugar-docs/sugar.html (PyDoc)] -- core UI and service libraries
* [[Sugar Architecture]] [http://www.vrplumber.com/sugar-docs/sugar.html (PyDoc)] -- core UI and service libraries
** [http://www.vrplumber.com/sugar-docs/sugar.activity.html Activity Support] -- support mechanisms for writing activities
** [http://www.vrplumber.com/sugar-docs/sugar.activity.html Activity Support] -- support mechanisms for writing activities
** [http://www.vrplumber.com/sugar-docs/sugar.presence.html Presence]
*** [http://dev.laptop.org/git?p=projects/hellomesh;a=summary] -- [[HelloMesh]] example activity using D-Bus Tubes, documented in [[Tubes Tutorial]]
*** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- example of using the Presence service in the [[Web]] activity
** [http://www.vrplumber.com/sugar-docs/sugar.datastore.datastore.html Datastore] -- activity's interface to the datastore service
** [http://www.vrplumber.com/sugar-docs/sugar.datastore.datastore.html Datastore] -- activity's interface to the datastore service
*** [http://dev.laptop.org/git?p=web-activity;a=blob;f=downloadmanager.py;hb=HEAD Example] -- usage of the datastore API in the [[Web]] activity's download manager
*** [http://dev.laptop.org/git?p=web-activity;a=blob;f=downloadmanager.py;hb=HEAD Example] -- usage of the datastore API in the [[Web]] activity's download manager
Line 94: Line 100:
Libraries for connecting to other processes, either on the local machine or across the network
Libraries for connecting to other processes, either on the local machine or across the network


* [http://dbus.freedesktop.org/doc/dbus-python/ D-BUS] [http://www.vrplumber.com/sugar-docs/dbus.html (PyDoc)] -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
* [http://www.vrplumber.com/sugar-docs/sugar.presence.html 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
* [[Telepathy]] [http://telepathy.freedesktop.org/spec.html Spec] [http://www.vrplumber.com/sugar-docs/telepathy.html (PyDoc)] -- buddy and connection management including cross-machine RPC over D-BUS
** [http://dev.laptop.org/git?p=projects/hellomesh;a=summary Example] -- [[HelloMesh]] example activity using D-Bus Tubes, documented in [[Collaboration Tutorial]]
** [[Shared Sugar Activities]] -- includes some minimalist code on how to use Telepathy in your activities
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- example of using the Presence service in the [[Web]] activity
** [http://dev.laptop.org/git?p=projects/sharedstate;a=tree;f=sharedstate;hb=HEAD SharedState] -- project to create a shared-object model over telepathy (used by [[Calculate]])
** [http://dev.laptop.org/git?p=projects/sharedstate;a=tree;f=sharedstate;hb=HEAD SharedState] -- project to create a shared-object model over telepathy (used by [[Calculate]])
** [http://dev.laptop.org/git?p=chat-activity;a=blob;f=pippy_app.py;hb=HEAD Example] -- the Chat activity uses Telepathy text channels
** [http://dev.laptop.org/git?p=chat-activity;a=blob;f=pippy_app.py;hb=HEAD Example] -- the [[Chat]] activity uses Telepathy text channels
** [http://dev.laptop.org/git?p=projects/connect-activity;a=blob;f=activity.py;hb=HEAD Example] -- the Connect activity uses DBUS Tube connections
** [http://dev.laptop.org/git?p=projects/connect-activity;a=blob;f=activity.py;hb=HEAD Example] -- the [[Connect]] activity uses DBUS Tube connections
** [http://dev.laptop.org/git?p=projects/read-activity;a=blob;f=readactivity.py;hb=HEAD Example] -- the [[Read]] activity opens an HTTP server running on a StreamTube to share files
** [http://dev.laptop.org/git?p=projects/read-activity;a=blob;f=readactivity.py;hb=HEAD Example] -- the [[Read]] activity opens an HTTP server running on a StreamTube to share files
** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/networkserver.py;hb=HEAD Example] -- [[Games/Productive]] uses an ExportedGObject shared over the same tube as [[OLPCGames]].mesh
** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/networkserver.py;hb=HEAD Example] -- [[Games/Productive]] uses an ExportedGObject shared over the same tube as [[OLPCGames]].mesh
** [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/NewsReaderLite.py?view=markup Example] [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/penguintv/NRLTube.py?view=markup Example] -- the [[NewsReader]] activity shares the current feed with joined members via an ExportedGObject (second link)
** [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/NewsReaderLite.py?view=markup Example] [http://penguintv.svn.sourceforge.net/viewvc/penguintv/trunk/penguintv/NRLTube.py?view=markup Example] -- the [[NewsReader]] activity shares the current feed with joined members via an ExportedGObject (second link)
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- the [[Web]] Browser activity shares the current URL
** [http://dev.laptop.org/git?p=web-activity;a=blob;f=webactivity.py;hb=HEAD Example] -- the [[Web]] Browser activity shares the current URL
** [http://dev.laptop.org/git?p=projects/write;a=blob;f=AbiWordActivity.py;hb=HEAD Example] -- the [[Write]] activity shares an instance of it's core control's AbiCollab interface across a Tube
** [http://dev.laptop.org/git?p=projects/write;a=blob;f=AbiWordActivity.py;hb=HEAD Example] -- the [[Write]] activity shares an instance of its core control's AbiCollab interface across a Tube
** [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=olpcgames-src/olpcgames/mesh.py;hb=HEAD 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.
** [http://dev.laptop.org/git?p=projects/games-misc;a=blob;f=olpcgames-src/olpcgames/mesh.py;hb=HEAD 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.
*** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/graphics/ui.py;hb=HEAD Example] -- use of [[OLPCGames]].mesh to create a "Game Lobby" interface for configuring a game to be played
*** [http://dev.laptop.org/git?p=projects/productive;a=blob;f=Productive.activity/productive/graphics/ui.py;hb=HEAD Example] -- use of [[OLPCGames]].mesh to create a "Game Lobby" interface for configuring a game to be played
Line 130: Line 137:
* [http://www.vrplumber.com/sugar-docs/yum.html Yum] -- package manager for RPM-based distributions
* [http://www.vrplumber.com/sugar-docs/yum.html Yum] -- package manager for RPM-based distributions
* [http://www.vrplumber.com/sugar-docs/rpm.html RPM] -- RPM manipulation library
* [http://www.vrplumber.com/sugar-docs/rpm.html RPM] -- RPM manipulation library

= Smalltalk Libraries =

* [[EToys]]

= D-BUS Services =

* [http://avahi.org/wiki/ProgrammingDocs Avahi] -- local service discovery, e.g. for finding particular services provided on the mesh network
* [http://cvs.gnome.org/viewcvs/NetworkManager/docs/NetworkManager%20DBUS%20API.txt?rev=HEAD NetworkManager] -- network management service
* [http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces Hardware Abstraction Layer Daemon (hald)] -- control of standard hardware functionality
* [[Presence Service DBus API|Presence Service]] -- friend discovery and collaboration primitives, including a description of the Telepathy API
** Telepathy Connection Manager
** Telepathy StreamEngine
* [[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
* [http://dev.laptop.org/git.do?p=hardware-manager;a=blob;f=hardwaremanager.py;h=3154b17553621cc41fa947cbff2756372e6e37ec;hb=HEAD 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
** [http://firmworks.com/QuickRef.html 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)
** [[Hardware Power Domains|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


== Building PyDoc Documentation ==
== Building PyDoc Documentation ==
Line 195: Line 169:


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.
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 [http://epydoc.sourceforge.net/ 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 =

* [http://dbus.freedesktop.org/doc/dbus-python/ D-BUS] [http://www.vrplumber.com/sugar-docs/dbus.html (PyDoc)] -- desktop messaging (Remote Procedure Call (RPC) and Asynchronous Signalling) engine
* [[Presence Service]] -- buddy discovery and activity collaboration layer on top of Telepathy
* [[Telepathy]] [http://telepathy.freedesktop.org/spec.html Spec] [http://www.vrplumber.com/sugar-docs/telepathy.html (PyDoc)] -- buddy and connection management including cross-machine RPC over D-BUS
** Telepathy Connection Manager
** Telepathy StreamEngine
* [http://avahi.org/wiki/ProgrammingDocs Avahi] -- local service discovery, e.g. for finding particular services provided on the mesh network
* [http://cvs.gnome.org/viewcvs/NetworkManager/docs/NetworkManager%20DBUS%20API.txt?rev=HEAD NetworkManager] -- network management service
* [http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces 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
* [http://dev.laptop.org/git.do?p=hardware-manager;a=blob;f=hardwaremanager.py;h=3154b17553621cc41fa947cbff2756372e6e37ec;hb=HEAD 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
** [http://firmworks.com/QuickRef.html 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)
** [[Hardware Power Domains|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 =
= See Also =

Latest revision as of 05:26, 10 November 2010

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

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

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
  • 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

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
  • 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)
  • Graphics API -- older document describing the sugar.graphics codebase, which is now largely deprecated