Developers/FAQ
How do I do networking in Sugar?
Recommended pattern for networking applications on the OLPC laptops is to use the Tubes/Telepathy system. This is basically DBUS remote procedure calls over telepathy networking. The Telepathy framework allows for session establishment and routing across strange network topologies. See Activity Sharing for a discussion.
Sample Code:
The laptops will have IPv6 and IPv4 connectivity, they can use "normal" internet networking primitives as available in Python, Scheme and C.
- Standard Python supports synchronous and asynchronous networking including basic web-servers and the like.
- Twisted will not be available by default on the laptops but partial installs of the framework could be included in your activities if you want to do lots of multi-protocol networking operations
- PyRO (Python remote objects) is another common Python networking RPC approach.
- XMLRPC/SOAP can be used to produce web services
Can I Wrap Tubes in Socks?
Can I wrap Tubes with a socket compatibility layer to get the NAT traversal features and the like, but use old socket-based code?
How do I create a persistent server/service?
- How do I register for start-time loading?
- Is there any dbus event service for loading only on response to messages? That is, not loading until there is an event of a given type, such as a presence event?
- Yes, of a sort, services are defined in .service files, these match a named service to an executable which is to provide that service. Thus one can register to handle requests for a given named service, but you still need to arrange to have that service called by something.
How do I access the special hardware?
While Sugar will run on many machines, the OLPC-XO has some special hardware which can be exploited by software.
Camera / Camera-as-video-camera (v4l2)
See GStreamer for general instructions and OLPCGames for Pygame-specific instructions.
Directional pad/buttons
- Have their own X key names
- Currently 4-button set mapped to arrow (cursor) keys
- Two separate buttons mapped to ??? (pageup/pagedown)
- See OLPCGames for Pygame-specific instructions, key layouts and discussion of using the directional pad for gaming situations
Touchpad / Glide Sensor
- Shows up as a normal mouse under X.
- This is not a multi-touch capable glide sensor.
Drawing pad (stylus pad)
- How to switch in/out of stylus mode?
- How to set interpretation parameters?
Audio-port probe
Best sample code currently available is in the Measure Activity.
- How to get access?
- You configure the ALSA mixer (using os.system in the example code) and then use gstreamer events to process a the incoming audio-buffer "handoff" using a fake data sink. You unpack the data from the string values and get integer values. (Or just use the utility class (AudioGrab) in the Measure Activity).
- What's going to come out when I get access (keeping in mind I (the developer) likely won't have the actual hardware available)?
- You are processing a stream of audio data. In the sample code you are configuring gstreamer to produce a stream of integers at 48000 Hz. You should be able to produce the same effect using gstreamer on any linux box using your normal microphone port.
Mode-switching code for the screen
Much of this is controlled via the HardwareManager service on DBUS. There is sample code for getting a reference to the hardware manager in the Read Activity, from there, simply call the dbus-exposed methods to set the values you want. HardwareManager controlled operations:
- Display Controller (DCON) data-source (CPU or DCON)
- DCON freeze/unfreeze
- backlight brightness
- keyboard light brightness
- color/black and white mode
How do we:
- set all 8 (4 distinct) settings for MODE_MONO_LUMA, MODE_CSWIZZLE, MODE_COL_AA (as distinct from just colour/black and white)
- query, change, and restrict screen orientation
- drop to a lower resolution for performance or ease of porting, such as 600x450 or 400x300
See also Display.
How do I create my activity GUI?
- Can I just use Cairo, Pygame or GTK directly?
- How can a non-GTK (or Qt) app fully interact with Sugar?
- At the moment the Low-level Activity API is quite involved
- Can be "fixed" by creating a wrapper in Python (e.g. the ClassicGnome activity with a performance and memory penalty)
- Can write various DBUS services using a GTK event loop to provide the required introspection services (implies that GTK must be loaded by every process, regardless of whether it is needed)
- Can alter your core event loop to cooperate with an embedded GObject event loop (PyGame allows this, for instance), with the small concern that this requires loading GObject into your process' memory space
- How flexible does the GUI need to be?
- Should be able to handle a resize-and-rotate event from the X server
- Should be able to handle internationalisation/localisation, including to right-to-left-written scripts
- What's the best development approach:
- Write outside Sugar, finish and debug, then port?
- For older PowerPC-based Macs, this is likely the best approach
- Write to Sugar, test and debug within the system?
- Usable if you can set up a reasonably-performing emulated system or upgrade your system to support Sugar directly
- Write directly on the XO
- Usable if you are comfortable with command-line Linux editing tools, or want to use EToys. As Develop becomes available this should become more approachable.
- Write outside Sugar, finish and debug, then port?
How do I package my activity?
- How do I work from an in-process activity (develop registration)?
- setup.py develop
- You can use sugar-activity to start the activity, but you have to manually close it (note that by default there is no way to easily kill a mis-behaving activity in Sugar)
- How do I produce a binary extension?
- On a workstation with Qemu, you can create a compilation workspace. (Using a Qemu qcow overlay lets you do this without corrupting your base OS image). Within that work-space, compile the packages you want using gcc, yum, and all the traditional tools. Package and upload the results.
- How do I share code between activities?
- How do I use (large, common) Python packages?
- The system will "unify" common files across packages, so if you have a large package and another activity also uses that package then the system will only store one copy of the package (using a file-by-file comparison).
- Numpy
- Matplotlib
- MySQL or PostgreSQL client code
- Twisted
- Zope Interfaces
- Pygsear, PGU or other PyGame extensions
- How do I provide my own base packages on top of which I have written dozens of applications?
- As with the common activities, the current plan is to have the system unify the packages on the laptop. There is a cost in that the packages must contain complete copies of their supporting framework for each activity.
- How do I use (large, common) Python packages?
How do I publish for others to download?
- The Activities page is where most users will go to find new Activities
- Any http (web) server can be used to distribute packages
- Users can download a .xo package, when the package completes downloading, they use the Journal activity to "resume" the downloaded package
- How do I tell users about updates to the packages?
Plan at the moment is to have file-sharing handled by the underlying system. That is, the system will simply notice that you have duplicate files with the same properties and hash and will share them between the two activities.
How do I test a Sugar activity?
- Use the standard logging module in Python where possible
- Start your activity normally, its logs will be sent to the ~/.sugar/default/logs/ directory named after your Activity's DBUS service
- You can use the built-in Log Viewer activity on production XO versions (build 649 and up), alternately you can just view the logs in a developer's console using less or vi
- If you like you can also use:
sugar-jhbuild shell sugar-activity YourActivityName
to run your activity from a shell and be able to drop into pdb or similar command-line debuggers.
How do I debug a Sugar activity?
If you start your Sugar activity from the command line (see above), you can insert a standard Python:
import pdb pdb.set_trace()
command into your activity and then use the Python debugger to step through your activity's behaviour. Note that this will "freeze" your application while you are working, so you may have display issues.
How do I edit with emacs on the laptop?
- Install MicroEMACS by copying this file to the laptop.
- Zile may be closer to what you expect from Emacs install this RPM this rpm file to get it.
How do I mount a USB drive?
Normally this is done automatically by the HAL when you plug the USB key into the laptop. It will show up as a directory in the /media folder. If, however, you had the USB key in when you started the machine, or the HAL doesn't recognize the key, you may not get the mount completed. In that case you can try manually mounting the key:
- Enter the linux shell mode
- First become root: $ su
- Then make a place to mount it: $ mkdir /mnt/usb
- Then mount the drive: $ mount /dev/sda1 /mnt/usb
- Don't forget to unmount it before removal: $ umount /mnt/usb
- If anything fails you should edit your /etc/fstab file to include the mount point, device, and filesystem for the device to mount.