OLPCorps Technical Manual

OLPCorps Teams - Please read the OLPCorps Technical Manual here: File:Corps Tech Guide.pdf

Overview of XO-1, Sugar, XS

The OLPC XO-1 laptop

The OLPC XO-1 laptop was designed to withstand some of the harshest conditions in world, and is extremely durable. In other laptops, the components most likely to fail are the hard drive and internal connectors. The XO was designed with no hard drive to crash and only two internal cables. For added robustness, the machine's plastic walls are 2mm thick, as opposed to the standard 1.3mm. The keyboard is designed for kids' hand sizes, and has a sealed rubber-membrane. The display is cushioned by internal "bumpers". Its wireless antennas, which have better range than typical laptops, also act as external covers for the USB ports and as the latch mechanism for opening the XO-1.

The XO-1 is designed with off-grid and outdoor usage in mind. The XO-1 has a unique screen with a special mode for outdoor use that takes advantage of the sunlight, letting it illuminate the screen like a book. Aggressive power management in the default software offering and a low processor clock speed also mean the XO-1 uses less power that most laptops. With continuous usage, the laptop's battery tends to last 3-4 hours off of a single charge. The charging mechanism is more flexible than that found in most electronics, accepting DC input ranging from 11 to 18 volts. The XO-1 is equipped with a built-in camera, microphone, and speakers. It has three USB ports, a headphone jack, and an audio input jack that doubles as an analog sensorinput port. Underneath the screen, there is an SD card slot.

There are some buttons and keys on the XO-1 that aren't found on most laptops. For different screen orientations (e.g., turned around and flipped down ebook-style), the "rotate" button on the bottom left of the screen tells your software to rotate its display by 90 degrees. A videogame controller-style "rocker" and "game buttons" are positioned beside the display for ebook reading and handheld-style gaming. Some keys on the keyboard are specific to interacting with Sugar, the default software that ships with the XO-1.

The XO-1 is designed for kids. The keyboard and carrying handle are kid-sized. The laptop is distinctively unique: bright green with funny looking antenna-ears, both to appeal to its users and discourage gray market traffic. There's no mistaking what it is and who it is for.

Quick Facts about the XO-1

• CPU: x86-compatible AMD Geode LX-700@0.8W processor with 433 Mhz clock speed
• NAND flash drive: 1 GB
• RAM: 256 MB
• Display: 7.5" Dual-mode TFT display
• Resolution: 1200 × 900 resolution (200 DPI)
• Antenna: 802.11 b/g, mesh implenting 802.11s draft standard
• Battery: removable LiFePO4 22.8 Watt-hour battery
• Battery life: 3-4 hours with continuous usage, longer with aggressive power management enabled
• Charging: DC input ranging from 11 volts to 18 volts.
• Repairing: simple disassembly with Phillips head #1 screwdriver

More Information on the XO-1

http://laptop.org/en/laptop/hardware/specs.shtml - Detailed XO-1 laptop hardware specifications

http://en.flossmanuals.net/XO - XO-1 manual

http://wiki.laptop.org/go/Support_FAQ - Frequently asked questions about the XO-1 and Sugar

Sugar

Sugar is the open source user interface that ships with the XO-1 laptop. Much like the XO-1, Sugar has many design considerations that are specific to use by children. For example, whereas most graphical user interfaces for computers use a tree-like "filesystem" metaphor, Sugar has the Journal, which is a portfolio of what the user has done on the laptop. Sugar automatically stores (or Keeps) the data from whatever the user is currently working on.

There are two types of content you can install in Sugar: Activity and Library bundles. The file extension used for Activity bundles is .xo, and the extension for Library bundles is .xol. Activities are Sugar's programs, mostly written in python. Library bundles are Sugar's static content. Library bundles are accessible through the Browse activity.

Though originally developed at OLPC for the XO-1, Sugar has spun off into an independent project, and is now being developed under the supervision of the non-profit foundation Sugar Labs.

OLPC is committed to supporting Sugar on the XO-1. In the past, OLPC has performed the integration of Sugar and Fedora Linux into something you can install on all XO-1s (a "signed build"). OLPC now works with Fedora to ensure the XO-1 hardware is supported by the Fedora operating system and graphical environments (e.g., Sugar, or Gnome).

The latest signed and stable version of the XO-1 installable Fedora + Sugar spin can be found at http://wiki.laptop.org/go/OS_images. The release notes for the latest stable build include step by step installation instructions. Customizing the software and installation on multiple XO-1 laptops is covered in the section Planning and Preparation.

Quick Facts about Sugar

Sugar is written in python and C, most activities are written in Python Most XO-1s with Sugar are running it on top of Fedora Linux Activity bundles have the extension .xo, library bundles have the extension .xol The classic desktop metaphor is to Sugar as.... Files are to Journal entries

Programs are to Activities

The task bar is to the Frame

More information on Sugar

http://en.flossmanuals.net/Sugar - Sugar manual

http://sugarlabs.org/go/Sugar_Labs/FAQ - Frequently asked questions about Sugar and Sugar Labs

http://activities.sugarlabs.org/ - Place to discover new .xo activity bundles

http://wiki.laptop.org/go/Activities/All - Larger list of .xo activity bundles

http://wiki.laptop.org/go/Collections - List of .xol library bundles

The XS - School Server

The XO School Server, or XS, is a Fedora Linux-based operating system distribution designed to be deployed alongside XO-1 laptops and wireless access points. While XO-1 laptops may be (and often are) used in school environments without the school server, the school server software provides some features that may be desirable to XO-1 deployments.

Sugar collaboration for over 30 laptops: without access point networking or a school server, the practical limit for simultaneous collaboration over the mesh is 30 laptops -- 10 on each wireless channel (1, 6 and 11). Adding a wireless access point (no XS) will also support up to 30 laptops, now all on the same channel. Adding a school server with 2 access points can accommodate up to 100 laptops. This increased capacity is due to the school server's "ejabberd" service, which acts as a central hub for delivering information between laptops.

XO automatic backup: the XS can automatically back up the Journals of the XO-1s registered to it and provides a web interface for restoring individual documents from journal backups.

Caching: Using XS' "Squid" service for web caching, sites which have been cached will be transferred directly from XS to XO, increasing access speed and reducing the amount of data downloaded from the Internet. This is especially important for sites with satellite connections and metered bandwidth.

Access to content: the XS can be used as a repository for content (e.g., PDFs, Wikipedia snapshots, videos) too large to include on each XO-1's 1GB flash storage. With their laptop registered and connected to the school server, a child can access the local schoolserver homepage easily from the Browse activity. With some preparation, dynamic web services (e.g., Moodle, Mediawiki, blogging software) can also be offered via the XS. An important consideration is the learning curve of the software and how students, teachers and technical supporters will be expected to interact with this system.

Quick Facts on the XS

The XS software provides: reliable collaboration over 30 laptops, web caching, extra content on the server-side, XO backups

More information about the XS

http://wiki.laptop.org/go/School_server - School server page on the OLPC wiki

http://wiki.laptop.org/go/XS_Recommended_Hardware - Hardware recommendations for school servers

http://docs.moodle.org/en/OLPC_XS_installation - Instructions for installing Moodle on the XS

Preparation and Implementation

Planning for Power

It is very important to plan and budget properly to provide power to each XO-1 laptop. Costs for metered grid, generator and solar power vary greatly by region, and can significantly affect per-laptop total cost of ownership.

Power strips and adapters

Since in most schools many laptops will be charging at once, power strips are a necessity. XO-1 power adapters are designed to be used with power strips that have sockets oriented parallel to the length of the strip, (e.g., = = = =). Power strips with a perpendicular orientation (e.g., || || || ||) are inefficient as adapters cannot take advantage of every outlet.

It's also important to know what type of outlets are available in your deployment region and the types of power adapters you are getting with your XO-1 laptops. Converters should be budgeted for.

Total power requirements and long term costs

This table shows an estimate of the total wattage required for running 100 laptops, a school server and a Vsat modem. Number of units avg. Watts Total power required Laptops 100 5 (15 peak) 500 Watts School Server 1 20 (24 peak) 20 Watts Connectivity (e.g., Vsat modem) 1 50 50 Watts Total Power 570 Watts

The total energy required to operate 100 laptops, a school server and Vsat modem over an eight-hour period is 570 Watts for 8 hours, or 4560 Watt-hours. If, for example, you wanted to generate and store this energy over the course of a two-hour period, you'd need roughly 11400 Watts generation capacity feeding a battery system with adequate storage capacity, assuming 80% efficiency.

The Deployment Workbook is a spreadsheet that can be used to plan for deployment costs, including the long term costs associated with power. The spreadsheet and instructions for use can be accessed at: http://wiki.laptop.org/go/Deployment_Guide/Workbook

Important considerations: Where will power come from? When and where will students charge their XO-1 laptops? During their time off from school?

Planning for Networking

Wireless access points

A list of wireless access points tested to be compatible with the XO-1 is available at http://wiki.laptop.org/go/Wireless_Access_Point_Compatibility . The XO-1 has known issues with WEP and WPA encryption. Wireless access points should be tested with the XO-1 before large scale purchasing. The XO-1 will only connect to wireless access point channels 1, 6, and 11. Access points should be laid out to maximize classroom coverage and minimize interference between one another. To be used with a school server, wireless access points must NOT be running as a DHCP server or running NAT. The school server requires control of that functionality.

School server

Important things to consider when planning for school server deployment include: how many school server machines will be needed? What specifications will the machines meet? Where will content for the server come from or how will it be developed? Who will perform server installation and maintenance?

These are the suggested number of access points for running networks with school servers: <20 laptops <50 laptops <100 laptops <150 laptops no server needed, but some functionality is useful server + 1 access point server + 2 access points server + 3 access points

Many different computers can act as school servers, it has been tested on desktops, laptops, and commercial servers. Since the XS software is based on Fedora, the server's components must be Fedora supported. An important consideration is that Internetconnected school servers require two network cards, one for connection to the Internet and another for connecting to the wireless access point (or a switch, for multiple access points). Recommended minimum specifications for the school server's processor, RAM and storage are as follows:

Server Laptops Supported Processor RAM Storage Small <20-25 466 MHz 256 MB 40-60 GB Large <150 1 GHz 1 GB 320-400 GB The Deployment Workbook covers planning for school server numbers and related costs. The spreadsheet and instructions for use can be accessed at: http://wiki.laptop.org/go/Deployment_Guide/Workbook

Installing the School Server

Before installing and configuring the school server, be sure your machine is set up properly. It should have two network cards and meet the minimum specifications to support the number of laptops it will be hosting.

Providing Content on the School Server

When a user is registered and connected to the school server, they can access the server's home page by going to http://schoolserver/ in Browse. There is a link to the school server on the Browse home page, as well. This corresponds to the folder /var/www on the server. The current home page is a broken Moodle login page -- you'll have to create your own index.html that links to the content and services set up on the server.

Resources:

http://wiki.laptop.org/go/XS_Release_Notes - Place to find the most recent school server build CD images and installation/configuration instructions for that release

http://wiki.laptop.org/go/XS_Installing_Software - Instructions on installing and configuring the XS software on a server

Customizing the XO-1

Customization Sticks and Reflashing

A customization stick is a USB sticks with a special set of files that prompt the XO-1 to install activity and library bundles during laptop bootup. This method of installation is often used for (1) installing activities and content during a laptop reflash, (2) adding extra bundles before XO-1 distributions and (3) distributing packs of required activities before lessons.

To create a customization stick, you will need customization-2.zip, which contains two special zip files (actos.zip and runos.zip) which tell the XO-1 to install the .xo and .xol bundles from the bundles/ folder during bootup. The contents of customization-2.zip should be unzipped directly to the root directory of a USB key, and activities and collections should be placed in bundles/.

To use a customization stick, place it in a laptop that is off and turn it on. The normal boot sequence will be interrupted and display which bundles are being installed. When the laptop turns off, remove the stick from the laptop. Sample customization stick directory structure: boot/ boot/actos.zip boot/runos.zip bundles/ bundles/SampleActivity.xo bundles/SampleCollection.xol Installing the OS and bundles at the same time (reflashing): Including an OLPC release image in the same USB stick as the customization files allows you to install both an operating system and content on laptops with only one action. To include the signed release 711 on our example stick, for example, we would place the files os711.img and its corresponding fs.zip in the root directory of the drive. To perform the reflash, we would:

1. Insert the USB stick into the XO-1 (plugged in to a power source)
2. Hold down all four game buttons (to the right of the display) and press the power button
3. Observe the laptop rewrite its memory with the 711 operating system, reboot, install

the included activity bundles, and shut down Note: reflashing wipes the XO of its entire contents, including entries in the Journal. Important Journal entries can be backed up to a USB stick via dragging-and-dropping in the Journal, or restored via a school server backup.

More information on customization sticks and reflashing:

Customization:

http://wiki.laptop.org/go/Customization_stick - Instructions on creating a customization stick

http://dev.laptop.org/~mstone/customization-2.zip - The files required for customization

http://wiki.laptop.org/go/G1G1_activity_pack - A pack of common activities to install on laptops. Note: this already includes the customization files. http://activities.sugarlabs.org/ - Place to find Sugar activities

http://wiki.laptop.org/go/Activities/All - Another place to find Sugar activities

Reflashing:

http://en.flossmanuals.net/XO/HowToFlash - XO manual instructions on reflashing

http://wiki.laptop.org/go/Clean-install_procedure - Wiki page on reflashing

http://wiki.laptop.org/go/USB_update - Illustrated guide to reflashing

Making Library Bundles

Library bundles, also known as collections, offer a way of "installing" textbooks and other media onto the XO. They are simple to create, as they essentially consist of a zipped-up folder with the content and some metadata. Content within library bundles can be any format that Browse can open directly or via the Journal, such as .html webpages with images, .pdf documents, .ogg music and video. Finished library bundles can be placed on a school server and downloaded with the Browse activity, installed from the Journal using a USB stick, or installed during laptop bootup using a customization stick.

Example Library bundle contents:

Samplebundle.xol is a .zip file that contains:

• samplebundle/ (a folder)
• samplebundle/index.html (a webpage)
• samplebundle/textbook.pdf (a pdf)
• samplebundle/library/library.info (a metadata file)

The library.info file within the content bundle contains metadata about the bundle itself. index.html is the webpage that Browse will load when a user accesses your bundle. It can be a simple page with some text, or it can have links to the media you have included in the bundle.

Example index.html text contents:

<a href="textbook.pdf">Your textbook</a> This displays a link to the textbook PDF, which the user can then click on and open the PDF from the Journal.

Example library.info metadata file text contents:

[Library]

• name = Sample global_name = org.laptop.sample
• long_name = sample simple textbook bundle # This is the description that will show up in the Browse library
• locale = en # The language this bundle is localized for
• library_version = 2 # The release number of this bundle
• category = books # One of: activities, books, health, images, media, science, search
• license = CC-BY-SA # The license this bundle is being released under. (see resources section for link to short names of licenses)
• host_version = 1 # Reserved for future use, leave alone
• l10n = false # Reserved for future use, leave alone
• activity_start = alternate_index.html # Optional. By default, Browse open this bundle's index.html file

There is an automatic library.info generator available, listed under "more information".

More information

http://wiki.laptop.org/go/Creating_a_collection - Instructions for creating a collection

http://wiki.laptop.org/go/Library.info - Sample library.info file and explanations of variables

http://bantha.org/~kraken/olpc/bundler/makeLibraryInfo.html - Automatic library.info generator

http://fedoraproject.org/wiki/Licensing - Contains list of short names of bundle licenses

Making Activity Bundles

http://wiki.laptop.org/go/Activity_tutorial - Tutorial on building a simple Sugar activity with PyGTK

http://wiki.sugarlabs.org/go/Modifying_Activities - Some tips on simple activity modifications that can be done

http://sugarlabs.org/go/Activity_Team - The Sugar Labs activity team

Custom Builds

Customizations beyond activity and library bundle additions can be accomplished by modifying the Fedora + Sugar operating system. Installing unsigned custom builds requires you to install a developer's key on each laptop you are installing it on.

More information on custom builds:

http://wiki.laptop.org/go/Customizing_NAND_images#Alternative_method - This is the preferred method for low level customizations of the OLPC Fedora + Sugar OS http://wiki.laptop.org/go/Activation_and_Developer_Keys - Information on

http://wiki.laptop.org/go/Multicast_NAND_FLASH_Update - Useful for re-imaging multiple laptops at the same time over the air

Troubleshooting

Hardware self-test

Knowing whether a problem lies within the software or hardware of the XO-1 is very helpful for deciding whether to reflash or disassemble and repair it. Open firmware includes hardware diagnostics routines for most major components of the laptop. This can be triggered by using a bootup cheat code: press and hold down the left hand side of the "Rocker switch" to the left of the screen and turn the XO on. The following components of the laptop will be tested sequentially by the hardware diagnostics:

• Battery - The current status of the main battery is read from it and printed out
• Manufacturing data - The manufacturing data of the laptop is printed out
• Memory - The SDRAM on the motherboard is quickly tested.
• Processor - The Processor is exercised. Press any key to skip to the next test.
• USB - The USB ports are exercised (for use with an oscilloscope).
• Audio - A stereo sweep is output over the speakers (headphones, if plugged in). Then audio is recorded using the microphone, and output (at low volume) over the speakers.
• Camera - Video is displayed on the screen from the camera for twenty seconds
• SD Storage - Any SD storage is quickly (and non-destructively) tested
• NAND Flash - The motherboard's internal NAND Flash storage is quickly (and non-destructively) tested.
• Display - The display is only marginally tested with color bars, then the drawing capabilities of the CPU are displayed for a while. Press any key to skip to the next test.
• Wireless networking - The firmware is loaded, the network co-processor booted and communicated with.
• RTC - The Real Time Clock, which includes parameter RAM, is tested
• Timer - various timers are tested
• Touchpad - Press any key to exit.
• Keyboard - Press ESC to exit.

You can pause between individual tests by holding down the "rotate" button on the left hand side of the screen (below the "Rocker switch").

Hardware Repairs

Once you have determined a problem is hardware-related (via firmware self-test or a reflash to no effect), you may want to replace a component in the laptop. XO-1 Laptop repairs require a Philips Head #1 screwdriver. Instructions for disassembling the top of the XO-1 (the screen portion) should be used if you need to repair or replace the display, game buttons, power button, microphone, camera, speakers or motherboard. The instructions with photos are available at: http://wiki.laptop.org/go/Disassembly_top

Instructions for disassembling the bottom of the XO-1 (keyboard and touchpad) should be used if you need to repair, access or replace the spare screws in the handle, keyboard, touchpad, mouse buttons, battery, wifi antenna latches or rubber feet. The instructions with photos are available at: http://wiki.laptop.org/go/Disassembly_bottom

Reflashing

Reflashing, as described in "Customization Sticks and Reflashing", will solve most software issues at the expense of Journal data and user-installed bundles. Important Journal entries should be backed up and restored when possible.

Resetting the EC

If an XO-1 laptop will not even begin to boot up, it may be a problem with the embedded controller (EC). To reset it, remove all power sources from the laptop:

1. Take the battery out and remove the power adapter
2. Wait two minutes to allow the embedded controller to lose all power and reset
3. Replace at least one source of power (battery or power adapter)

The battery LED should flash orange momentarily (about a quarter of a second) when power is first reapplied. If you do not see this flash, you either have a motherboard hardware problem or faulty EC firmware installed. The general solution to both of these problems is to replace the motherboard.

Restoring backups from the School Server

Once laptops are registered to the school server, backups of laptops' Journals are taken approximately once every 24 hours. Restoring backed up Journal items can be done from any XO-1 through the Browse activity. Open browse, click on the school server link, then edit the address bar to go to http://schoolserver/ds-restore . Select the serial number of the machine you want the backup from (which can be found in the Control Panel-->About my XO), and choose which Journal files to download.

Misc. troubleshooting resources:

http://wiki.laptop.org/go/Wifi_Troubleshooting_Guide - Troubleshooting issues with wifi

http://wiki.laptop.org/go/XO_Troubleshooting_AV - Troubleshooting sound issues

http://wiki.laptop.org/go/Support_FAQ - Support frequently asked questions

Finding Support, Providing Feedback, and Online Resources

The XO-1 and Sugar both have fantastic communities built up around them, enthusiastic about supporting and improving their offerings. Honest feedback from teachers and students in deployments is especially valued.

http://wiki.laptop.org/go/Support_FAQ - Frequently Asked Questions about OLPC, the XO, and Sugar

mailto:help@laptop.org - Email for volunteer-run support queue for the XO-1 laptop

http://lists.sugarlabs.org/ - Sugar Labs mailing lists

http://lists.laptop.org/ - OLPC mailing lists

http://activities.sugarlabs.org/ - Sugar activity ratings and comments