This is an old revision of the document!


XO Laptop Resources

Getting Started

Using the XO Laptop

General Tips

  1. Makes sure you are using the newest version of Sugar on your XO
  2. There is no password for root so it is fairly easy to brick the XO by messing up the
  3. CTL-ALT-ERASE is the XO equivelent to CTL-ALT-DEL on a windows computer, you also need to do this anytime you make a change in Terminal before it will take effect
  4. When the touchpad gets too sensitive it needs to be recalibrated
  5. The battery tends to die in about 1.5-2 hrs of constant use
  6. Be very aware of the hardware limitations
  7. There is a slot on the lower right hand side of the screen where a SD card can be inserted if you need extra storage space.

Sugar GUI

Sugar is the Fedora Linux based operating system used by OLPC on their XO laptops and now maintained by SugarLabs.

Main Views TODO: expand this

  • Activity
  • Home
  • Group
  • Neighborhood

Important Activities

  • Terminal: this is your command prompt and will allow you to navigate without the GUI
  • Pippy: a python editor and interpreter
  • Develop: an activity writing program
  • Browse: a basic web browser
  • Write: a basic document editor based off of AbiWord.

Shortcut Keys

  • Neighborhood View: shows everyone and all activities on the network and what networks are in range
  • Group View: shows your friends on the network
  • Home View: shows available activities
  • Activity View: shows most recently used activity that is still open, if nothing has been open this goes to the journal
  • Frame: shows activities open, battery and volume status, and friends connected to you in activities

Notes/Issues from Previous Classes

Issue #1

Issue: (Team Awesome + Team PuffAdder)
Porting games from pygame and python to the OLPC and creating activity bundles

Description:
The wrapper for pygames (OLPCGames-1.6) and the instructions for how to use it from the OLPC wiki are not usable

Approaches Tried:

  • tried the wrapper as root
  • tested to see that program ran in python from the terminal
  • tested to see the that the files were all there
  • tried the wrapper with manually moving the files
  • tried the wrapper not as root

Solved:
1/15/09
Cut and Paste the code to a website or email
Cut and paste from there to Pippy
Save from pippy as an activity bundle

Additional Thoughts:
1/16/09
While this works, it may not be the best way to do and we may need to figure out how to get OLPC-Games to wrap correctly. Why? When you open up your new pippy-made activity, it will open two windows. One is the window actually made by pippy, and the other is your pygame. Now, no other activities work like that which leads me to believe that ultimately the way we have it set up is wrong. Very sad, yes, I know. I'm wondering if OLPC-Games, if we were able to get it to work, will wrap (which to my understanding is what its supposed to do) the pygame into the sugar activity window.


Issue #2

Issue: (Team Awesome)
Getting Glade GUI designer to work on a mac

Description:
Glade does not have a package installer for mac and very sparse instructions for getting it working on a mac

Approaches Tried:

  • downloaded Fink with Fink Commander
  • opened Fink Commander and ran update-all
  • searched for glade
  • downloaded glade3
  • tried to install glade3 with default response set
  • install failed
  • found issue online
  • downloaded XQuartz version of x11
  • reinstalled glade3
  • closed x11
  • restart x11
  • run glade3 from x11

Solved:
1/16/09
install XQuartz version of x11 before glade3


Issue #3

Issue: (Team Awesome)
best virtual machine to run the OLPC image in

Description:
was looking for an easy to use, reliable VM

Approaches Tried:
looked at the ones recomended by OLPC

Solved:
1/16/09
settled on using Virtual Box instead


Issue #4

Issue: (Team PuffAdder)
Touchpad being very hard to use

Description:
Very hard to use the touchpad

Approaches Tried:
Pushing hard on the touchpad

Solved:
1/16/09
You need to recalibrate the touchpad! Do this by pressing the buttons in the four corners of the keyboard (right arrow “end” key, the frame key, the escape key, the function key). However, make sure that you press the function key LAST and make sure there is nothing on the touchpad.
Another thing that sometimes works is to open or close the frame or change to home view (Team Awesome)


Issue #5

Issue: (Team Meow)
Unable to get use wget to retrieve from the wiki

Description
If you try to use wget in order to retrieve files form the wiki it actually copies the formatting of a wiki page instead of the file

Approaches Tried
We attempted to change the colons in the filepath to backslashes however this gives the same result. The reccomended solution atthis time is to post code you need for the olpc to your website on copland or some other web page in order to use the wget command.

Partially Solved:
The current solution is more of a work around. This appears to be more of a problem on the wiki end rather than the olpc end.

Getting ready to program for the XO

Install Python on your computer

For Windows Users:
  1. Python
    1. The first step in this process is to download a copy of the Python installer, this can easily be accomplished via Python’s website.
      • Online guides will frequently point you toward ActivePython, while this program is highly rated it also requires an email subscription to access the download. For this reason I have avoided using it
    2. Go to Python’s website ( http://www.python.org )
    3. Click on “Downloads”
    4. Select the appropriate Windows installer and download it.
      • Python 2.6.5 is the most recent stable release of python, both on Windows and in Unix-like environments. The Pygame (see step 3) website, however recommends 2.5.4 for Windows; it should be noted that this recommendation is from August 2009.
    5. After the file is completely downloaded, open the containing folder and open the executable file you just downloaded
    6. Follow the installer instructions
      • This method of installation will also install the default Python IDE (called IDLE) for editing code, there is additional information needed to install Python for a different IDE such as Emacs, Eclipse, or VI
  2. Pygame
    1. Go to the official website for Pygame ( http://www.pygame.org/ )
    2. Click on the “Download” tab from the main page
    3. Under the sub-category Windows select the appropriate version of the installer for your machine (this is completely dependent on which version of Python was installed in Step1)
      • If one were to install the build for Python 2.5.4 they would then want to download the Pygame installer file titled “pygame.x.x.x.win32-py2.5.msi” (where the x’s represent the version number of Pygame). A release is also provided for Python 2.6.*.
    4. Find and open this update to Python, it will run an automated installer
    5. Upon completing the setup be sure to test that functions and other aspects of Pygame are working correctly.
For Ubuntu (or similar Unix Distributions)

Python

  • Being a developer friendly environment, Ubuntu comes with a pre-installed and fully operational version of Python
  • Otherwise, one would the package manager of your specific distribution to download the necessary files…
  • Ubuntu/Debian use aptitude:
# apt-get install python
  • RHEL/CentOS/Fedora (this includes your XO) use yum:
# yum install python
  • Gentoo/Sabayon use portage (consult documentation about USE flags for these distributions):
# emerge -av python
  • These package managers are to be executed from the terminal command line, a shell (search “term”). They must be run with root (administrator) privileges, using the “sudo” command.
  • To access Python, simply enter ‘python’ in the command shell; this will allow one to interact with the Python interpreter via the shell
  • The pre-installed build of Python on Ubuntu does not come with an editor, however, it is fairly easy to configure Emacs or any other editor to be used with the language.
    • To install Emacs you can, once again, use a package manager like apt-get
# apt-get install emacs21
  • Python's default editor, IDLE, is also friendly for programmers new to python, and can be installed with the package manager.

Pygame

  • Pygame is not a standard library for the Python programming language, therefore it is not included in your Ubuntu environment and must be installed
  • As mentioned in Step 1, the package manager can be made use of to install applications and packages – the same can be done to install the Pygame graphics library using:
# apt-get install python-pygame

Set up your XO

Development Environment

These are general ideas of things you should do and understand before trying to program for the XO

  • Turn on your XO and go to the control panel and give it a new name and choose a new color for your XO man
  • Flip through and understand the different views: Neighborhood, Group, Home, and Activity
  • Look at the information available in the frame
  • Investigate the journal and how to open and save files there
  • Try to start a chat with one other person, then try to add more
  • Try to share various games and see what works and what doesn't
  • Investigate the different mesh and wireless networks available and how they appear
  • Make a friend
  • Go to the Terminal Activity and play around, try to figure out the filesystem layout

Text Editor

Have you ever went into the terminal and typed “emacs activity.py” and been confronted with a horrible error? A horrible error saying something similar to “emacs command not found”? Then this is the tutorial for you! And it is only two or three easy steps…

The first thing you should do is install emacs, so open a terminal. Make sure you’re connected to wifi because it’s going to download all of the files:

su
yum install emacs

Wonderful! Now you have emacs with just two simple commands in the terminal.

However, you’ll soon notice when you try to open it that you get an error saying

"Font `-adobe-courier-medium-r-*-*-12-120-75-75-*-*-*-*' is not defined"

No problem! If you follow the instructions on OLPC’s emacs page, they say to delete the adobe-courier-medium line from a file. However, if you do that, when the window opens the font is unbearably small to read. So, I suggest doing this instead in the terminal:

emacs -nw ~/.bashrc

And add the following line to the end of the file:

alias emacs='emacs -nw'

What you just did was told bash (your shell) to run the command ‘emacs -nw’ every time you type ‘emacs’. This opens emacs within the terminal instead of a window, and looks much better.

Note: This won’t work until you restart your shell. So you can either restart the terminal or just type ‘source ~/.bashrc’.

Preparing for crashes

  • Run the auto-update feature for the operating system through the terminal
  • Run the auto-update feature for the activities through the start menu
  • Trying to double click on an activity will cause it to freeze and require a restart of the XO
  • DO NOT try to open more than three activities at the same time
  • Save work early and often
  • Create a USB drive for your group with the image of the operating system so that if you brick your XO is can be fixed quickly
  • Keep a backup copy of all of your code on a USB or another computer (hint: version control software!)

Getting used to Linux

Familiarity with the Linux family of operating systems can be useful when dealing with the XO. If you haven't done so before, you might consider installing Linux on a machine you have access to. Ubuntu is a distribution that is particularly suited for beginners, and Fedora (the basis for the XO operating system) is good for intermediate users. The Gentoo installation process is considerably more involved, but upon completion you will have a better understanding and appreciation for Linux. For Windows users, the Ubuntu CD provides Wubi, a Windows program that allows Ubuntu to be installed without re-partitioning your computer. Sun Microsystem's VirtualBox provides Windows and Mac OS X users the ability to install any flavor of Linux as a virtual machine inside their existing OS, free of charge.

Some usefull links related to Linux:

Emulating the XO

  • The XO Laptop Wiki recommends using the QEMU emulator for emulating the XO
    • Windows – A pre-packaged, easy-to-install QEMU image/emulator is provided for windows users.
    • Mac OSX – Provides a guide to setting up Q.app (QEMU for Mac OS X), as well as Sun VirtualBox.
    • Linux – The Linux instructions for QEMU are a little bit more in-depth, but the instructions are easy to follow.
  • Virtual Box has been found to work very well too
  • Run two instance of Sugar at the same time (great for testing networked games)

Install the sugar package that comes with Ubuntu to use their Sugar Emulator. You can actually open up two different emulators and have them act as two different XOs. This will help with testing mesh networking on your laptop.

Open two different emulators using these two seperate commands:

ubuntu-prompt$ SUGAR_PROFILE=cat sugar-emulator ubuntu-prompt$ SUGAR_PROFILE=dog sugar-emulator

Note that cat and dog can be anything, as long as they are different.

Working in a Software Development Team

Document Your Work

Presentation Tips

General:
  • Plan presentations! Decide who will say what ahead of time.
  • Give short overview before explanations
  • Avoid “Powerpoint Hell”!!
    • You will bore your audience to death with information overload.
    • Pictures are interesting! Paragraphs are boring.
    • Keep slides sparse, generally no more than 3 bullets, with brief phrases only.
  • Start by giving a brief introduction about who we are and what we are presenting.
  • Don't block anyone's view of the projected image.
  • Brief, to the point and descriptive
Code:
  • comment functions briefly, effectively.
  • show color
  • should fit on one screen (modularity)
Explanations:
  • write bullets, explain verbally; wiki is good
  • show how you derived a particular solution
  • list trial and error efforts
  • talk about what went wrong
  • What is finished, what needs to be done.
  • Timeline of when each component will be done.
  • Timeline of when the entire project will be ready.

Final Presentation guidelines from previous semester

Testing

  • Test on both emulated version and real XOs, behavior often differs
  • test often and document results
  • start by testing single player versions then move to multiplayer versions
  • test simple network function and build off of that

Version/Revision Control Software

The use of a SVN is highly recommended. Emailing code will get very tedious and causes problems when multiple people are making changes at the same time.

Reading the Subversion books will allow you to better understand the mechanics of version control with SVN. It is available at: Subversion Book
The most important chapters are Basic Usage and Branching and Merging.

Repositories hosted with the ECE/CIS Dept. for use with class projects will be provided to each group.
UD CIS students will require an ECE/CIS “acad” account to access the repositories. If you do not have an acad account, you can apply here.
The EECIS Subversion documenatation page provides additional information about using the ECE/CIS subversion servers.

Open Source Software

All software for the OLPC project is supposed to be open source and allow for the community to build upon each others work.

Designing Learning Games

The following links are resources from the ACM Digital Library related to the development of educational games. You will need to be on the campus network to access them.

These papers are published in the IEEE Xplore Library, and will also need a UD network connection to access.

Programming for the XO laptop

Some Python Notes

Recursion

  • Default limits recursion to only 1000 levels deep
  • Recursion limit can be changed by using “sys.setrecursionlimit(int limit)”
  • The typical windows build has a hard limit of 2000 levels of recursion
  • Python is not optimized for tail recursion
  • Recursion uses a lot of memory, not good on an OLPC
  • It is recommended to use loops instead of recursion when possible

For those new to python, the following links can be of great benefit:

Some Slides from previous classes:

Python Examples

A separate page has been created that contains example python programs and games made by previous classes.
Python Example Programs

XO API and Software

Extracting activity source code from .xo actvity files

When an application is ready for deployment on the XO, the source code is packaged into a .xo file which can be natively imported by the XO laptop. If you need to obtain the source code for an XO application, there are 2 possible ways to do it:

If the program has been imported as an XO activity:

  • The source code may be found in the directory called /usr/share/sugar/activities/ACTIVITY_NAME.activity
  • For reasons unknown at the time of this writing, the XO does not always add a .activity folder for an imported .xo file.

If you have access to the .xo file:

  • Mac OS X / Linux
    • Open a bash terminal, and navigate to the directory containing your .xo files.
    • use the command 'unzip' to unzip the .xo file into the target directory.
    • Type 'man unzip' to get information on how to use the unzip tool.
    • If you want to see the contents of the .xo file without extracting it, type 'unzip -l FILENAME.xo'.
    • Use the mkdir command to create a directory for each .xo file to be extracted into.
    • Extract the source files by using the following command:
      • unzip FILENAME.xo -d DESTINATION_DIRECTORY
    • The source code for the application can be found in DESTINATION_DIRECTORY/bin/

Bundling activities for the XO

Pygame

Pygame provides a relatively simple API for programming games in python, and is incredibly usefull for animations. It does not however, provide GUI elements such as buttons/text fields/menus/etc. These must be created by hand when using pygame.

Pygame Tips

Vista and PyGame Instructions

If you have Python (2.5 or higher) and PyGame 1.8 installed, you should be good to go. I've tested crashRun on both MacOS X and Windows and I hope it'll run on Linux, too.
If you need Python, you can download it from: http://python.org/download/
And PyGame is available here: http://pygame.org/download.shtml

Vista users note: when I tried the python installer on a Vista machine, the installer didn't modify the PATH to include Python (it appeared to on XP). You can set this variable by right-clicking My Computer in the Start menu, selecting Properties, Advanced, and then pressing the Environment Variables button. You'll need to append “;C:\Python25\” to the end of the PATH variable.

Issue : The Frame does not display anything or freezes (Team Meow)
Description: So the code brings up a window however nothing changes or updates in it or it freezes.
Solution: Chances are you forgot the pygame.display.flip() command. This should go at the end of any code that makes changes to the screen. The command works by updating the screen or other display you are using.

Issue: pygame window stays all black on windows XP in eclipse
Description: pygame window stays black until window is minimize and then re-opened
Approaches Tried: none, it works on windows vista
Solved: use pygame.display.flip() after draw function

Issue: Can’t get sound files to work properly
Description: Using the pygame.mixer.Sound() function alone will not produce sound
Solution: Using the pygame.mixer.Sound() function requires a larger wrapper function written around it. We wrote this function that makes using sound really easy.

#This function will play a specified sound file for a given
#amount of time
#@param:  sound_file (string) - the path to the file to play
#@param:  ticks (int) - the length of time to play the file (in ticks)
#@note: This function must be used in conjunction with some type of event handling
def play(sound_file, ticks = 1):
    sound = pygame.mixer.Sound(sound_file)
    clock = pygame.time.Clock()
 
    sound.play()
 
    while pygame.mixer.get_busy():
        clock.tick(ticks)

Changing the ticks seems to have no effect on the sound, however, not including the ticking did not produce sound.

XO Directory Structure

Here is a representation of the default directory structure for XO

/
 '- activities
 '- boot
 '- etc
 '- lib
 '- media
 '- ofw
 '- proc
 '- sbin
 '- selinux
 '- sys
 '- usr
 '- bin
 '- dev
 '- home
   '- olpc (AKA ~)
     '- OLPCGames-1.6
       '- Skeleton
         '- Your Home Made Acitvities end up in here
 '- mnt
 '- opt
 '- root
 '- security
 '- srv

XO Networking Resources

Some Links regarding the Mesh Network:

Bluetooth

Helpful XO Programming activities

  • Pippy – Python environment designed to teach programming concepts.
  • Terminal – The all-powerfull terminal.
  • Develop – Developer tools for the Sugar environment.

Miscellaneous

Connecting the XO Laptop to a Projector

The XO-1's can be projected if they are upgraded to Sugar 10.1.3 (build 860) using a USB2VGA connector. We have tested this using Startech's connector.

The XO runs slower when projecting, will only display an image on the remote screen, and the connector must be plugged in before the XO is started.

Version Numbers

See this page which describes how to check your XO version. The information is most likely found under “Control Panel : About my XO”.

Build, release, and update information.

CCCS has XO-1's with build 802.

“OLPC is not the only one making XO-1 operating system builds. You can also obtain builds from others in the wider community” (link).

  • Sugar Labs build: Dextrose, Sugar 0.88, Fedora 11.

How to differentiate between XO-1 and XO-1.5?

Success with getting to the OK prompt by holding the “X” game button when powering on, and then hitting ESC when prompted to halt the normal startup. So, the laptops at CCCS all appear to be unsecured, and that we will not need a developer key.

CCCS XO machines

  • XO series: (CT4Y machine: XO-1)
  • Sugar OS version: (CT4Y machine: 8.2.1 if not upgraded)
  • Python version: (CT4Y machine: 2.5.1)
  • PyGame version: (CT4Y machine build 802: 1.8.0, CT4Y machine build 852: 1.8.1)
    • pygameversion.py
      import pygame.version
      print "PyGame version:", pygame.version.ver
  • OLPCGames version: (CT4Y machine: won't be installed. It is only installed on xo machines that are used to develop games and publish xo files. xo files can be transferred to other xo machines without OLPCGames.)
  • Security: disabled

Reflashing

Reflashing will restore the XO to its factory settings. This process can be used for upgrading or downgrading the XO. Directions can be found in the Floss manual. While off, insert a USB stick with the image to reflash with, and while holding down the four game buttons, power on the XO.

Sugar on a Stick

With Sugar on a Stick (SOAS), you can boot directly to the Sugar OS on any machine without the need virtualizing or emulating Sugar. Students can use the journal on the stick to save their work.

Download Page, Instructions for creating the SOAS.

Versions:

  • v1, Strawberry (Fedora 11), Released: 6/24/09
  • v2, Blueberry (Fedora 12), 12/8/09
  • v3, Mirabelle (Fedora 13), 5/25/10, Sugar 0.88
  • v4, Mango Lassi (Fedora 14), 11/2/10, Sugar 0.90??
  • v5, Name?? (Fedora 15), ?/?/?, Sugar ???

With Mirabelle+, you can customize your SOAS with a specialized activity set.

TODO Research how to bundle CT4Y activities with SOAS.

Virtual Machine

We have a virtual machine set up for our server needs. An acad account is required to use it.

Host: cisc367.acad.cis.udel.edu

Log in instructions:

  • ssh into the vm using your acad credentials (Note: you will first be placed into your normal working directory.)
  • enter the command “eecis_su cisc367”. (This will change you to user “cisc367” if you have the correct permissions, and change your working directory to /home/cisc367.)

www docs are located in /home/www/htdocs/

Example Communication via POST

This file passes data via the POST method to the server. The server will log all data passed by $_POST[“data”]. So in this example, “test data from python again” will be passed.

The server script post-server.php catches this string and appends it to an output file test-output.txt.

Try it out, and run this python script from your local machine!

python-client.py
'''
Richard Burns
November 28, 2010
 
Test script which passes information to the class apache server via the POST method.
 
The server script currently captures this information and appends it to a testing
output file, demonstrating one way that we can pass data to the server for it to 
record.
 
Taken from:
http://docs.python.org/library/httplib.html
 
TODO: test size limitations of the POST
'''
 
import httplib, urllib
 
#params = urllib.urlencode({'milk': 1, 'eggs': 2, 'bacon': 0})
params = urllib.urlencode({'data': "test data from python again"});
 
headers = {"Content-type": "application/x-www-form-urlencoded",
                "Accept": "text/plain"}
 
conn = httplib.HTTPConnection("cisc367.acad.cis.udel.edu:80")
 
#conn.request("POST", "/cgi-bin/query", params, headers)
conn.request("POST", "/post-server.php", params, headers)
 
response = conn.getresponse()
print response.status, response.reason
data = response.read()
conn.close()

The htdocs directory is publicly viewable at cisc367.acad.cis.udel.edu.

The form.html file can be used to test the php server-side script without the need for the python client.