User manual

     This page is an unofficial community project, and OpenPandora Ltd. is not responsible for its content.

Pandora FTW!

So your Pandora just arrived after being in the post for two months. Jolly good! But now that it's actually here, what on earth do you do with it? Don't panic! Let's take a look at what's included in the box(so you don't miss anything!) and then hop on over to setting it up for that extended Ms. Pacman marathon I know you've been waiting for!

Also, don't forget to hit up GP32X for questions/info/apps/fun/discussion!

Safety Information

Warning: Choking Hazard, do not let children under the age of 3 come close to your Pandora console. The Pandora Contains small parts that can be eaten by those children.

The battery of Pandora must be charged by the charger included with the Pandora(see package contents) and we at OpenPandora Ltd. cannot be responsible for people using third party chargers. Please be aware that some third party chargers compatible with the Pandora have a fake CE logo and are highly dangerous (they will burst into flames).

Keep the Pandora in normal temperatures under 140F/60C (Recommended temperatures are in the range between -10C and 40C). The battery is standard Lithium Polymer battery. Do not keep near fire or water. Do not disassemble, destroy or damage the battery, or it may explode! Do not short circuit external contacts! Dispose of it properly, please.

All third party modifications and hardware/software can damage your Pandora, OpenPandora Ltd cannot be responsible for damage caused by this. Trusted software can be recognised by a OP-member in the Pandora Appstore. See the “OP-Team Trusted” image in the app store to see if the software application can be trusted.

The Pandora has a 4.3-inch Touchscreen. You can touch the screen to trigger an action. Although this is a touch screen, you cannot punch it. Always touch the screen gently – this will be more then enough to trigger the action you want.

The Pandora has an protective design, making it hard to break. Of course, you should never drop your Pandora, wash it, or try anything that can harm your Pandora. This will void your warranty.

Warranty Information

By law there is a one year warranty, and the device will be replaced/repaired if it is faulty. LCDs with noticeable dead pixels will also be replaced (Note: Pixels are small squares aligned in a grid to make up the image on your screen. A "Dead Pixel" is one that doesn't work anymore and remains black or any other static color).

Box Contents

When you first open Pandora's box, a slew of demons and raging emotions may forcibly leave the box. This is normal. After that, you may or may not be surprised to find a:

• Pandora console
• Stylus (located in stylus slot on the side of the Pandora)
• Battery
• DC Wall Charger
• TV-Out Cable (ONLY if you ordered it separately)
• Carrying Case (ONLY if you ordered it separately)
• Extra Battery (ONLY if you ordered it separately)

After you take those things out, you may find a sliver of Hope left over. It's best to keep it, as you never know when you could use some Hope.

Specifications

Highlights

• ARM® Cortex™-A8 600Mhz+ CPU running Linux*
• 430-MHz TMS320C64x+™ DSP Core
• PowerVR SGX OpenGL 2.0 ES compliant 3D hardware
• 800x480 4.3" 16.7 million colours touchscreen LCD
• Wifi 802.11b/g, Bluetooth & High Speed USB 2.0 Host
• Dual SDHC card slots & SVideo TV output
• Dual Analogue and Digital gaming controls
• 43 button QWERTY and numeric keypad
• Around 10+ Hours battery life**

*The 600Mhz+ can be higher or lower. This can be controlled by software designed for the device.

**Is affected by use. (example turn bluetooth on or off during play time)

Advanced Specifications

• Texas Instruments OMAP3530 processor at 600MHz (officially)
• 256MB DDR-333 SDRAM
• 512MB NAND FLASH memory
• IVA2+ audio and video processor using TI's DaVinci™ technology (430MHz C64x DSP)
• ARM® Cortex™-A8 superscalar microprocessor core
• PowerVR SGX530 (110MHz officially) OpenGL ES 2.0 compliant 3D hardware
• integrated Wifi 802.11b/g (up to 18dBm output)
• integrated Bluetooth 2.0 + EDR (3Mbps) (Class 2, + 4dBm)
• 800x480 resolution LTPS LCD with resistive touch screen, 4.3" widescreen, 16.7 million colors (300 cd/m2 brightness, 450:1 contrast ratio)
• Dual analog controllers
• Full gamepad controls plus shoulder buttons
• Dual SDHC card slots (up to 64GB of storage currently)
• headphone output up to 150mW/channel into 16 ohms, 99dB SNR (up to 24 bit/48KHz)
• TV output (composite and S-Video)
• Internal microphone plus ability to connect external microphone through headset
• Stereo line level inputs and outputs
• 43 button QWERTY and numeric keypad
• USB 2.0 OTG port (1.5/12/480Mbps) with capability to charge device
• USB 2.0 HOST port (480Mbps) capable of providing the full 500mA to attached devices (examples include USB memory, keyboard, mouse, 3G modem, GPS)
• up to two externally accessible UARTs and/or four PWM signals for hardware hacking, robot control, debugging, etc.
• un-brickable design with integrated boot loader for safe code experimentation
• Power and hold switch useful for "instant on" and key lockout to aid in media player applications on the go
• Runs on the Linux operating system (2.6.x)
• Dimensions: 140x83.4x27.5mm
• Weight: 335g (with 4200mAh battery)

Features

The Pandora is a mixture between a PC and a gaming console (similar to classic computers such as the Amiga). That's why it has gaming controls (Buttons, DPad and analogue nubs). It is fast enough to emulate many other systems, run a full desktop, access the internet via Firefox and play games such as Quake3. However, it is not as big as a netbook. Believe it or not, it will fit in your pocket. It's a bit bigger than the Nintendo DS. (See Applications section of this manual to see what applications your Pandora will come with.) Remember that your Pandora console will get better with every application installed!

First Time Use

Now that you've opened the box, let's set this thing up! Place the battery inside the battery compartment on the back of the Pandora, making sure the contacts touch(the little silvery metal bits, it's easy). Snap on the battery cover and you're all set!

Charging

Charge your Pandora 8 hours before disconnecting it from the wall charger. This will improve the lifetime of your battery. To charge the Pandora, insert the power cable end in the Pandora and the other end into your wall socket.

The battery comes pre-charged at 40%, and that level might have decreased during shipping. To be on the safe side, we recommend that you charge the Pandora before you use it. Simply plug in your wall charger into an outlet, or optionally use a mini-USB cable connected to a computer or wall adapter. For extreme silliness, plug your Pandora into an already charged Pandora, and charge it from that! But not really.

First Boot

Once your Pandora is ready, turn it on. The OS will take some time to boot up for the first time (about 10 minutes, this is only for the first boot, and is normal). After it has booted, a series of settings dialogs will pop up in the shape of a "Boot Wizard" allowing you to alter your Pandora's settings to your liking.

There are a total of 3 parts to the Boot Wizard guide:

System configuration

The first thing you will have to do is to calibrate the Pandora's touch screen. Only do this if the screen isn't calibrated already. You will have the option for touchscreen calibration the first time you boot up your Pandora console.

Note: "Calibrating the touch screen" is a term used to describe the process of matching coordinates given by the touch layer with the underlying screen. A badly calibrated screen will register your push elsewhere on the screen, perhaps half a centimeter to one side. As there are sometimes slight variations in the production of the touch layer, you the user can improve the accuracy by matching the two layers manually.

User setup

After calibrating your screen, you will have to enter your full name. This is what you will see in any user selection dialogs or when the system needs to address you, so enter whatever you are most comfortable with. Then follows your username. It is recommended to choose an all-lowercase, one-word username here, since you will have to enter this name every time you log in. Once you've entered your username, a password input dialog appears. You will have to enter the password you want to use twice here. If you don't want to have a password for your device, simply leave both fields empty. If, however, you decide to enter a password, something hard to guess and between 8 and 16 characters long is preferred.

Network and security settings

You will now have to enter a name for your Pandora. This will be the Pandora's host name, so you have two options in this situation:

1. If you don't have a domain you want to connect to, simply enter any name here. It should not contain any spaces.
2. If you do have a domain you want to connect to, enter a name in the form of "pandoraname.domainname.tld". Note that you may never have a use for this.

Then, you'll have to choose whether you want to automatically log in on your Pandora when it boots, or if you should be given the opportunity to log in as a different user, or enter your password. It is recommended to disable auto login if you want to protect your user data, but if you're often in a hurry, then you can enable auto login here.

The final thing you will have to choose, is whether you want to use the full desktop Xfce environment or the gaming-oriented PMenu environment as your default environment in the Pandora. It is recommended to choose Xfce here if you want to gain access to the Pandora's full potential. This option can be changed later at any point.

Calibrating The Touchscreen

The touchscreen in your new Pandora device isn't psychic! You have to tell it what to do, and in order to do that effectively, you need to calibrate it. Simply navigate to settings→screen→calibration wizard and follow the onscreen instructions. You may have to recalibrate the screen from time to time as well.

During the first boot wizard, you will be offered the option to calibrate the touchscreen. By default it may well work okay, but the option is there. If calibration is far off, use the keyboard to select the calibration option.

Basic Use

Desktop style environment

On the Desktop

The desktop will contain icons for numerous locations (such as each mounted SD card), as well as any auto-discovered pnd-applications located on SD cards or internal NAND.

In the menu

On the bottom left you have your applications menu, similar to the Windows start menu. Clicking it brings up a list of all installed applications and pnd-applications in the appropriate location on your SD cards.

Miscellaneous

To the right may be some icons, these serve as shortcuts to commonly used applications. Next to that you have your taskbar which, as you might have guessed, lists all running applications in your current workspace. To the right of the taskbar you have your workspaces, think of these as multiple desktops. By default you have two to switch between. Applications running in one workspace will not be visible in the other, so you can effectively hide your Ms. Pacman game from your boss at work, because there's no way you're not going to go for the gold, even at work! Finally there are a few more icons that deal with TV-Out, network connectivity, etc. and some running applications may place an icon there as well. And to the right of THOSE, you have your time. Because time flies when you're using your Pandora! Badum tsh. And to the right of that, you have a little icon which, when clicked, displays all running applications.

Finally, I'd just like to reiterate this--EVERYTHING is customizable! We'll get to that section later, but for now, let's just check out the applications on your Pandora.

Buttons

Xfce menu

The Pandora button will bring up the applications menu, letting you quickly enter a search to locate an application to run or perform operations against running applications.

Power Modes

Without switching the device entirely off, it may be placed into low power mode or regular power mode; simply pressing the power button will toggle modes.

Consider low power mode to be akin to turning off a PDA or cellphone -- the screen is off, the CPU is clocked down and so on, but the device is still silently on, allowing for alarms to go off or it to be turned on again instantly. Regular power mode is for normal usage.

Low power mode is probably going to be used as the normal "off" for most people, with true off (device powered down entirely, unable to respond to alarms or wake up quickly) available to conserve battery power. Turning the Pandora off completely is the best option if you don't plan on using it for few weeks or longer.

Closing the lid will turn off the display but otherwise leave the device operating - handy for audio playing; turning off the display lowers power use.

The actual behaviour of buttons and events can be customized.

Basic Linux user guide

New to the wonderful world of Linux? No problem! You don't need mad terminal skills to open a web browser, but it can be nice to know what you're doing once in a while.

The structure of the file system

If you're used to the file system of e.g. MS Windows, you will find that a Linux file system is rather different from what you're used to. In this section, we will go through everything you have to know in order to feel comfortable with using the Pandora's file system.

Basic philosophy

In Windows, you have multiple file system roots, called "drives", that are labeled with different letters, like "C:" or "D:". In Linux, there aren't multiple root directories, but rather just one root directory, called "/". All other directories are inside of this directory, including other drives.

Common directories

Inside of the root directory ("/") are quite a lot of other directories. Here are the most important ones:

• "/home" - This is where all of the files that are owned by all users are stored. Users do not generally have write-access to anything outside of this directory.
• "/home/username" - Here are the personal files of user "username". In this directory, you will find a directory called "Documents", "Pictures", "Desktop" etc. that correspond to that users personal directories. This directory is also called "username"'s home directory, and can be abbreviated with "~/" (if you're currently logged in as username) or "~username/".
• "/boot" - This is the directory where the Linux kernel is stored, and other files that are needed at boot time can be accessed. Do not touch this directory (You can't even do it if you wanted to)!
• "/bin", "/lib" - System binaries and libraries are stored here. Most of the terminal commands mentioned below can be found inside of "/bin". You should generally never have to touch this directory, either.
• "/usr" - Here is where you'll find programs and files installed by the user. Core applications such as the web browser, media player, and other applications that are available the first time you start your Pandora are stored here. If you decide to install anything via the "ipkg" command (covered later), this is where the files needed by those installations will end up.
• "/etc" - System-wide configuration. Should only be touched by power-users.
• "/media/*" - If you connect USB drives, SD cards or other external media, you will find that the contents of that media have been placed here.

Don't worry if this doesn't make any sense; It was thought up by bearded engineers back in the seventies. They liked the idea that everything would be in a predictable place, but this is no longer completely the case.

Basic Terminal Commands

Note: Linux is case sensitive. This applies to filenames and directories too. "/home/me/stuff" is a different folder than "/home/me/STUFF", you can actually have both. You can have "/home/me/Stuff" too if you like, and all three are separately recognised directories.

Navigation

In the terminal, you are always in some folder. Think of it like being in a file manager: you can see the contents of the directory you're in, you can do things with those files, or you may decide to go to some other folder and continue your work there.

There are a few essential commands that are used to navigate around your system via the terminal:

• "pwd" - Print the current working directory (will print e.g. "/home/user")
• "ls" - List directory contents (similar to "Dir" in Dos, and the Linux command "dir" will actually emulate the DOS command if you want to!)
• "cd <directory name>" - Change to a different directory, eg. "cd music" or "cd /home/me/music"
• "cd .." - Go up one directory level (similar to "cd.." in Dos)
• "cd" - Go back to your home directory (similar to My Documents in Windows)
• "cd -" - Go back to the previous directory you were in (handy if you forget)

Controlling Running Apps

• "top" - View running processes (like the Task Manager in Windows) press "q" to quit
• "killall [program name] - Stops running process (use with care)

File Manipulation

• "rm <filename>" - Remove a file, eg. "rm somefile.txt" or "rm /home/me/randomfiles/somefile.txt"
• "rmdir <directory>" - Will remove a directory, but **only** if it is empty!
• "rm -r <directory>" - Will remove a directory and its contents ("-r" means recursive)
• "rm -rf <directory>" - Will remove a directory, all of its contents, without asking you first. Use with extreme care. ("-f" means force)
• "mv <original filename> <new filename>" - Moves a file to a new place, also used for renaming, eg. "mv somefile.txt somefile_backup.txt" will rename it, but "mv somefile.txt /home/me/backup/somefile.txt" will move it. This will also work for directories.
• "cp <file to copy> <new filename>" - Copy a file, eg. "cp twoweeks.txt twomonths.txt" copies into current directory, while "cp twomonths.txt /home/me/ihaveadream/twoweeks.txt" copies to another directory.
• "cp -r <directory to copy> <new directory name>" - Copy a directory and all of its contents to another location.
• "touch <new file name>" - Makes a new (empty) file
• "mkdir <new directory name>" - Makes a directory

Misc.

• "cat <filename>" - Prints the contents of a file, eg. "cat hellolo.txt"
• "clear" - Clears screen, terminal input begins at the top again
• "date" - Your friend, the terminal will tell you the date
• "cal [month] [year]" - Makes a pretty calendar, eg. "cal 12 2009" or "cal * 2010" or "cal 1 2010 > fingers_crossed.txt" sends output to file
• "history" - Gives a list of the recent commands you have run. Running !number (e.g. !15) will rerun that numbered command in the history list

History Search: Press CTRL-R. As you type, BASH will try and find the command in your recent history that most closely matches what you are typing. To get back to the prompt, press CTRL-C.

Autocompletion: Press TAB. The terminal (also called the shell) will attempt to intelligently figure out what you're trying to type. It needs something to work with however, so try pressing TAB half way through a command or location.

eg. "cd /home/me/pandora_suc" *TAB* will complete it as "cd /home/me/pandora_success" or with a filename "cat /home/me/letters/i_want_the_pandora_to_fa" *TAB* will turn into "cat /home/me/letters/i_want_the_pandora_to_fall_into_my_hands"

Directory aliases: There are some special directory names you can use to refer to a directory that would be too long to type otherwise, or that you simply don't know the name of.

• "~" - Refers to your home directory e.g. "/home/user".
• "~seconduser" - Refers to someone else's home directory.
• "." - Refers to the current directory, or the "same directory" in a path. What this means, is that if you type "cd .", nothing will happen since you already are in ".", and if you type "cd somedir/././././././.", you will simply go to "somedir", since the "."-directories that come after it are the "same directory" as the one before them.
• ".." - Refers to the directory in which the current directory is, or the "parent directory" in a path. If you type "cd .." you will come to the parent directory of your current directory, and if you type "cd s1/s2/s3/../../..", nothing will happen, since the path you specified cancels itself out.

Applications

Many applications will come preinstalled into the internal NAND; these will be regular Linux applications (not packaged into pnd files, since they do not need to be redistributed to anyone.)

Additional applications may be found as pnd-files (see below, a packaged up single file representing an entire application) or as regular Linux files (an application likely being made up of many files and possibly needing installation.)

What Is Included?

• Ångström Linux: Lightweight beautiful Linux-based operating system for the Pandora.
• Xfce: A full featured window manager for Linux.
• Midori: A full features web browser, designed to be lighter and faster than a full desktop style browser.
• OpenOffice: Full desktop document managing. Edit, create and manage your documents on the go. (really??)

Where Can I Get More Apps?

There are many ways to get more applications onto your Pandora.

• The easiest way is to browse the Pandora App Store, where you can download a selection of free or commercial applications. To download, navigate to an app, pay for it if you must, and hit the 'download' button. Select where you want to save it, and you're done!

• There is the good ol' Pandora File Archive.

• There are nice repositories, such as the Angstrom ARM Repository, or...

• The Pandora includes the package manager ipkg.

• Also, people may upload their apps to weird crevices in the net, so be on the lookout! (or use a search engine)

Introduction To .PNDs

What Are .PNDs?

A .pnd ("pandora") file is an application (game, word processor, emulator, whatever.) More accurately, it is a full application bundled up into a single file; think of it like a zip, with a relatively well defined internal structure.

The pnd-file system was designed so you could use an application without the hassle of installation or uninstallation, or even having to organize it yourself if you don't want to. You just download or obtain the pnd-file, and use it.

If you remember classic computers such as the Amiga - where you inserted a disk and then launched the applications read by Workbench (the Amiga's operating system) - then this is similar: when you insert an SD card into one of the two slots, the (Linux based) Pandora OS will scan it for your PND program files. Any program it finds will either turn up on the desktop or the application menu (just like in Windows).

More details can be found in the "libpnd hub" part of the wiki, but that is more oriented to techies and developers.

How do I run a PND-application?

Put your pnd-files in your SD (see below for some suggestions where.)

A pnd-file is usually invoked in one of the following ways

• browse to the file using the directory browser, and click to run it. (.pnd files are file-associated to another program, pnd_run which knows how to run them.) This lets you organize pnd-files in directories of your choice on the device NAND or SD.

• in PMenu, the applications will be shown by name; you can just select and run them from the menu

• for pnd-files placed into /pandora/menu on SD, the application will be shown in the Start menu on the device; use your stylus or buttons to invoke it

• for pnd-files placed into /pandora/desktop or /pandora/apps on SD, they will show up automatically on your desktop; invoke them with the stylus, your finger, or controls as you see fit

Where Do .PNDs Go?

Put .pnd-files into specific directories if you want them to show up in the Start menu or on your Pandora desktop, or in Pmenu.

You can put them anywhere you like in internal NAND or SD, if you wish to organize them yourself and launch them with taps.

/pandora/desktop -> pnd files show up on the desktop

/pandora/menu -> show up in the Applications menu (by the developers suggested categories.)

/pandora/apps -> show up in the desktop, and in Pmenu

These locations are not written in stone. The "libpnd" config files are in /etc/pandora/conf in the NAND. Generally you will never need to alter these files, but you certainly can if you wish. In theory, obliterating the files will still leave the system working, and they are easily restored. One file, /etc/pandora/conf/desktop defines the "search paths" to look for .pnd files, and where to put ".desktop" files when they are found. The searchpaths says where to find them (such as /pandora/desktop), and where to put the application link - /usr/share/applications is where the menu items are pulled from. IF you wish to put pnd files somewhere not in the searchpath, just add the directory to the search-path and you're good to go.

Where does my data go? How do I make files visible to the applications?

An application normally will see what is contained within the pnd-file, or your personal data created with the tool; it can of course look anywhere on the SD or device internal memory. For example a Quake port might expect to see extra level files in /quake, or give you a way of selecting a path to put files in.. or it might just expect it to be in your personal data folders, or in the pnd-file itself. Its up to the application, with suggestions in the pnd-guidelines for developers.

The first time a pnd-application is run, an "app data" directory is created for it; anything that app data folder contains will be visible to the application as if it was in the pnd-file (and in fact, this lets you override files in the pnd-file without modifying the .pnd itself, which could be handy.) If your app creates a file "foo", it'll show up in /pandora/appdata/appname-id as "foo". The actual appdata folder name depends on the name used by the developer, but should generally look like application-name and some funny number afterwards. It should be easy to spot.

ex: Quake 1 will probably put score or save data in /pandora/appdata/quake1-123/ or somesuch.

It will always be helpful to read the description or readme file included.

Q: How do I make ROMs available to an emulator?

For something like ROMs, hopefully a developer consensus will lead either to a canonical location, or a convention of having a directory picker or browser present, so that ROMs can be stored in SD locations of your choice; doesn't strike me as something that should be in a pnd-file, or to be pretended to be in a pnd-file with appdata tricks.

Q: How do I make pak-files available to Quake?

For some add-ons or data needed for a game, the developer may require it to be 'in the main application path'; as mentioned above, just drop it into the appdata folder and the app will just see it.

More Info About .PNDs

Visit libpnd_hub for more information!

Configuration

Updating The Firmware

Given a working firmware, you might wish to patch it with official Open Pandora patches; you might also wish to just grab an application from the Angstrom repository, say.

In both of these cases, an ipk file will be made available. (In the future, an automated system may offer to patch up your device or auto-download patches. TBD.)

An ipk file is a compressed installable package.

It should be easily used, but from the Terminal if you wish to manually apply an ipk to patch the firmware, install or update an Angstrom application, it is simple: opkg install foo.ipk

Replacing the Firmware

Rather than patch the firmware, the firmware may be replaced wholesale with a freshly downloaded firmware.

Booting a Firmware from SD

The hardware is capable of booting entirely from SD; if the device is bricked or otherwise has a blank NAND, this could be an option. furthermore you're able to try out alternative operating systems without needing to reinstall your primary operating system.

Steps include:

• Preparing the SD card(s)
• Setting up the firmware on the SD card

Preparing the SD card

There are two main approaches:

• Setting up the firmware on on SD card (meaning you need two partitions - a boot partition, and a firmware partition), and
• Setting things up across two SD cards - meaning you boot from one SD card, and have the firmware on the other.

Operating from one SD card provides you the option of still being able to use the other; operating across two cards provides you he option to have a regular boot-SD, and flip between multiple other SDs for the actual firmware, should you wish to cycle between many operating systems (say.)

The boot partition generally must be FAT32, and then the kernel, MLO and other files need to be unpacked upon it.

The firmware partition must be either ext2fs or ext3fs; under Linux, such a partition can be easily created:

mkfs.ext2 -L LABELNAME /dev/mmcblk0p2 - assuming LABELNAME for the partition - assuming /dev/mmcblk0p2 for your SD device; you'd better check this carefully ;)

Oops! I Borked My Pandora!

Fear not, young netizen! Your Pandora was designed to be unbrickable, so unless you used the ancient art of alchemy to physically turn your Pandora into a brick (or you just broke the hardware inside), you should be okay!

Pandora FAQ

Silly goose, go to the FAQ page for more detailed information.