Difference between revisions of "User manual"

From Pandora Wiki
Jump to: navigation, search
(Where Can I Get More Apps?: best place to look right now is on the wiki)
(Basic Use: general cleanup.)
Line 156: Line 156:
 
minimenu is designed as a fast and easy to use launcher, without a lot of fancy frills. A grid of icons to launch, and use the d-pad or touchscreen to fire one off. It is fairly configurable and skinnable and is fully featured, and very fast. If you recall the interface on the gp32, gp2x, wiz, and gmenu2x you will be right at home and then some!
 
minimenu is designed as a fast and easy to use launcher, without a lot of fancy frills. A grid of icons to launch, and use the d-pad or touchscreen to fire one off. It is fairly configurable and skinnable and is fully featured, and very fast. If you recall the interface on the gp32, gp2x, wiz, and gmenu2x you will be right at home and then some!
  
====The main grid====
+
=====The main grid=====
  
 
The main grid with the default skin has most of the screen realestate showing a grid of available 'auto discovered' applications, with a detail panel on the right. A list of tabs is across the top of the screen, with some short help message on the bottom.
 
The main grid with the default skin has most of the screen realestate showing a grid of available 'auto discovered' applications, with a detail panel on the right. A list of tabs is across the top of the screen, with some short help message on the bottom.
Line 170: Line 170:
 
The standard overrides are supported -- .ovr files for icon title, clockspeed setting and categories, as well as a .pnd for icon override.
 
The standard overrides are supported -- .ovr files for icon title, clockspeed setting and categories, as well as a .pnd for icon override.
  
====Configuration and tricks====
+
=====Configuration and tricks=====
  
 
minimenu has a fairly comprehensive configuration file for its minimalistic design; most options may be enabled or disabled or fiddled with, and the skin can reasonably be altered.
 
minimenu has a fairly comprehensive configuration file for its minimalistic design; most options may be enabled or disabled or fiddled with, and the skin can reasonably be altered.
Line 190: Line 190:
 
[[Minimenu Configuration Documentation | This section contains more information.]]
 
[[Minimenu Configuration Documentation | This section contains more information.]]
  
===Desktop style environment===
+
===Desktop style environment (Xfce)===
  
====On the Desktop====
+
=====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.
 
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====
+
=====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.
 
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====
+
=====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.
 
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.
+
Finally, I'd just like to reiterate this--EVERYTHING is customizable! We'll get to that section later on.
  
===Buttons===
+
===Pandora Button===
  
====Xfce menu====
+
When in the desktop style environment (Xfce), the Pandora button will bring up the applications menu, letting you quickly view the available applications. If held, it allows you to [[User_manual#Killing Applications | kill]] an unresponsive application.
  
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 | Power Modes]]===
 
 
===[[PowerModes]]===
 
  
 
Without switching the device entirely off, it may be placed into low power mode or regular power mode; simply sliding the power switch to the right will toggle modes.
 
Without switching the device entirely off, it may be placed into low power mode or regular power mode; simply sliding the power switch to the right will toggle modes.
Line 220: Line 218:
 
Closing the lid will turn off the display but otherwise leave the device operating - handy for audio playing; turning off the display reduces power consumption.
 
Closing the lid will turn off the display but otherwise leave the device operating - handy for audio playing; turning off the display reduces power consumption.
  
Shutdown will only occur if you are unplugged from the wall. The device can't be charged while off, to "fast charge" just switch to low power mode. See [[PowerModes]] for more info.
+
Shutdown will only occur if you are unplugged from the wall. The device can't be charged while off, to "fast charge" just switch to low power mode. See [[Power modes | power modes]] for more info.
  
 
The actual behaviour of buttons and events can be customized.
 
The actual behaviour of buttons and events can be customized.

Revision as of 02:17, 15 July 2010

     This Wiki is an unofficial community project, and Open Pandora Ltd. is not responsible for its content. Neither is the Wiki an official source of information about your device
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 you've been waiting for!

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

If you find a problem which is not explained after visiting the forum, be sure to report it in the BugTracker

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). Open Pandora Ltd. will not be responsible for damage arising from the use of third party chargers. Please be aware that "cheap" third party chargers often carry fake CE logos. These can damage your Pandora or burst horribly into FLAMES.

Keep the Pandora in normal temperatures under 140F/60C (Recommended temperatures are in the range between -10C and 40C)[citation needed]. The battery is a 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.

Modifications to hardware can damage your Pandora. Open Pandora Ltd cannot be held responsible for any resulting damage.

Malicious software can do horrible things to your Pandora. Only download Pandora software from trusted locations such as the Pandora App Store, or the websites of trusted developers. See the OP-Team Trusted image in the App Store to see if the software application can be trusted.[citation needed]

The Pandora has a 4.3-inch touch screen. You can touch the screen to trigger an action. That's right, a touch screen - not a stab screen, punch screen, or solid mahogany workbench. Always touch the screen gently – this will be more than enough to trigger the action you want.

The casing of the Pandora has been designed for maximum strength, making it quite hard to break. Please do not consider this a challenge. Do not drop, throw, clamp, launch, tumble dry, or place anvils on the Pandora. This will void your warranty.

Warranty Information

A one year warranty applies as required by law, and the device will be replaced/repaired if it is faulty. LCDs with numerous/excessive dead pixels will also be replaced.[citation needed]

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 should find the following items:

  • Pandora console
  • Stylus (located in stylus slot on the side of the Pandora)
  • Battery
  • Mains power adapter (charger)
  • Battery case

The following items should also be present if you ordered them separately:

  • TV-Out Cable (As of 05-25-10 these are not yet included in the box and will ship separately as available)
  • Carrying Case
  • Extra Battery

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

[citation needed]

  • 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 clocked higher or lower. This can be controlled by software designed for the device.
**Is affected by use. (For example, turning Wi-Fi off will give better battery life.)

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 (ABXY buttons, d-pad, and analogue nubs). It is fast enough to emulate many other systems, run a full desktop, access the internet with Firefox and play games such as Quake III. 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 original Nintendo DS. (See the 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.

To "fast charge" just put the system into "low-power" mode. You cannot charge the system while _off_. This is currently a feature and may change in future versions of the firmware.

As an added note by MWeston: IF YOU POWERED THE SYSTEM WITHOUT A BATTERY, SHUT IT OFF BEFORE STICKING THE BATTERY BACK IN.

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 Analog Nubs [1]

The nubs automatically calibrate with use, and do so every time the unit is freshly powered up. Calibration information is stored inside the nub RAM, so when you power down (full power off, not just low power mode) the calibration information is lost. Calibrating the nubs is as simple as just using them -- do a few left right up down moves or swoosh around, and the nub will know its boundaries and be good thereafter.

So no special effort is required to calibrate or use the nubs, but the first few motions you use of them may be erratic as they self-calibrate.

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[verify credibility] 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.

Mouse (stylus/pointer) settings

When done with the calibration and you are back in the Pandora Xfce desktop environment you might also want to change some other touch screen settings to make navigation with the stylus work according to your preferences. Two recommended settings to experiment with for easier navigation are:

  1. The double-click Time setting
  2. The double-click Distance (valid touch-screen double-click area)

In the first setting, i.e. Time, you will be setting the interval between double-clicks where such clicks will be accepted as valid. Ex. if you set the time to 250ms, the second click (or screen-tap in our case) must occur within 250ms of the first to be valid.

In the second setting, Distance, you will be setting the radius of screen area where the second click (tap) must fall into to be considered as a valid second tap. This means that if, for example, you set the distance to 5, your second tap must fall within a circle radius of 5 pixels from the point where the first tap occurred.

These two settings can be found under: Desktop ---> Xfce menu ---> Settings ---> Mouse ---> Behaviour tab.

Basic Use

Pmenu

TBD.

minimenu / mmenu

minimenu is designed as a fast and easy to use launcher, without a lot of fancy frills. A grid of icons to launch, and use the d-pad or touchscreen to fire one off. It is fairly configurable and skinnable and is fully featured, and very fast. If you recall the interface on the gp32, gp2x, wiz, and gmenu2x you will be right at home and then some!

The main grid

The main grid with the default skin has most of the screen realestate showing a grid of available 'auto discovered' applications, with a detail panel on the right. A list of tabs is across the top of the screen, with some short help message on the bottom.

Pressing Start or B will invoke the pnd-application. Presseing Select will switch to a basic menu, providing shutdown or some advanced options.

Pressing "Y" (think "Why?") will bring up pnd-application documentation, if that pnd-file has defined any.

The left and right shoulder triggers will switch categories of applications; by default, minimenu includes an All category and defaults to showing it.

The applications are auto-discovered in the same means as the xfce desktop and pmenu and other pnd-supporting systems, however you may add additional minimenu-specific searchpaths into the configuration should you wish to. It is likely a basic file browser will also be added, letting you launch applications manually placed on your SD cards.

The standard overrides are supported -- .ovr files for icon title, clockspeed setting and categories, as well as a .pnd for icon override.

Configuration and tricks

minimenu has a fairly comprehensive configuration file for its minimalistic design; most options may be enabled or disabled or fiddled with, and the skin can reasonably be altered.

The All category can be removed if undesired.

Expert conf hackers can specify what categories they'd like and in what order, and have multiple app categories dumped into one tab, and other tricks.

pnd-application icons may be all loaded during the menu setup, or deferred until later and loaded in the background.

Preview pics may be loaded up front (not advised, as it can be slow), or deferred until later. (When deferred, they may load when you rest the selection, or load in background.)

You may choose to have auto-discovered applications registered into any of their 6 categories (Main, Sub1, Sub2, Alt, AltSub1, AltSub2).

Etc and so on.

Additional keys are supported: Q to quit the menu (not really useful for most people), and Space to invoke the application.

This section contains more information.

Desktop style environment (Xfce)

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

Pandora Button

When in the desktop style environment (Xfce), the Pandora button will bring up the applications menu, letting you quickly view the available applications. If held, it allows you to kill an unresponsive application.

Power Modes

Without switching the device entirely off, it may be placed into low power mode or regular power mode; simply sliding the power switch to the right 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 reduces power consumption.

Shutdown will only occur if you are unplugged from the wall. The device can't be charged while off, to "fast charge" just switch to low power mode. See power modes for more info.

The actual behaviour of buttons and events can be customized.

USB Peripherals

You can connect USB2 High Speed peripherals directly, using the large USB connector, or a USB-OTG adaptor lead. Lower-speed USB devices will only work through a hub, the Pandora does not have the support circuitry inside to drive the interface in the correct mode. See the the USB compatibility list for peripherals which have been tested so far.

Killing Applications

Killing (or forcibly closing) an unresponsive application is as simple as holding down the Pandora button (just under start and select) for a few seconds. A dialog will appear which lists the open applications and gives you the option to kill them.

Forcing a Restart

Occasionally something will happen causing your Pandora to become unresponsive (to the point that even killing a program isn't possible). When this happens it is necessary to force your Pandora to restart. The easiest way to do this is by holding the Pandora button and moving the power switch to the right.

Setting Up WiFi

Setting Up Bluetooth

Adjusting Brightness/Contrast

Brightness can be raised by pressing Fn+I and lowered with Fn+U. A tool is included with the Pandora called "LCD-Settings" (under the "Settings" menu) which can be used to adjust the brighness and the gamma.

Changing Your Theme

Under "Settings" in the menu, you will find "Appearance" which will let you adjust the style, icon set, fonts, and a few other appearance related settings. Also, under "Window Manager" you can adjust the style of each window's title bar.

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.
  • Lightweight office utilities including Abiword, Gnumeric, and ClawsMail.

[volume needed]

Where Can I Get More Apps?

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

  • On this wiki, we maintain up-to-date lists of games, emulators, and other software, with download links. These lists are more comprehensive than the two official sites below, because not every program is submitted to both of them.
  • The easiest way is to browse the Open 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!
  • 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)
     Note: Pandora's internal memory (NAND) will be at close to capacity when you receive your Pandora. All new programs should be installed to SD card. Downloads from the Angstrom Repo, or use of the Ipkg package manager, should only be done by advanced users or when instructed by Open Pandora Ltd (for example, firmware updates).

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

/pandora/mmenu -> show up only in minimenu, ignored by the rest of the system

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.

NOTE: You can actually put subdirectories into those locations above, should you wish to organize your pnd-files somehow within those larger categories.

Where do .PND files NOT go?

.pnd files are looked for in the directories mentioned above; that list can be tailored if you wish to edit config files.

.pnd files are not looked for in the / (root) of the SD cards.. this is _on purpose_; consider, if your SD card is 32GB, or if yo're using a 2TB USB drive even -- it could have tens of thousands of files on it; having the Pandora scan the entire device for pnd files would take forever. Instead, we made a well defined set of directories the system will use - /pandora for everything, with 'appdata' and 'menu' and 'desktop' and other special purpose directories.

We could perhaps add / (root) of SD, without checking subdirectories, but thought it may run into confusion; we may add that later. But currently, the system will scan all subdirectories of the directories named above, so you can organize pnd files within those directories if you like.

If I want to override the .PND icon, name, or other settings, how? (Slightly advanced topic)

The easiest way right now is via the "override" (or "overlay") system -- .ovr files.

An .ovr is just a text file you create, with the same name as the pnd-file and in the same location, but with a different file extension. Piece of cake.

If your pnd-file is Hatari.pnd, and you're putting it into /pandora/desktop, then you might create an ovr file for it as: /pandora/desktop/Hatari.ovr If you wish to provide your own icon, create it with the same location and filename, but as a .pnd file: /pandora/desktop/Hatari.png

.ovr files are automatically supported by the system so should work across all pnd-application aware applications and desktops. .png icon overrides have to be handled by the menus, but are already handled by minimenu and anythign using the .desktop system (such as xfce full desktop or other standard desktop environments.)

An ovr-file simply looks like this:

The ovr file may (at this time) override the icon title, the CPU clock speed to set on launch, the main category, and the first subcategory for the main category. Additional fields will become overridable.

Minimenu honors up to 3 lines of 'notes', pulled from the .ovr file. (Make sure they are in the right subapp group). note-1, note-2, note-3, see example below. The notes in minimenu are shown at the bottom of the detail text panel.

[Application-0]
title                   HatariHack0
maincategory            Audio
maincategorysub1        Emulator
[Application-1]
title                   HatariHack1
clockspeed              200
note-1                  My text for note line 1

Notice the Application-0 and Application-1 -- any given .pnd file may include multiple applications, so you need to assign your overrides to the correct "sub application". It can be tricky to figure out which subapp you wish to override, but there are some tricks. minimenu, for example, shows the subapp-number in the detail panel. When looking at a .desktop filename, you'll notice #0.desktop .. some number after the # is the subapp-number.

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.

Example: Hatari

Hatari (Atari ST emulator) by default is set to look in "./disks" for the disk images (ROMs) to use. What this means is within the pnd-file (where no disks are supplied), and in the appdata directory. With Hatari, you can browse anywhere from the UI and pick a disk anywhere on your SD cards, but by default it'll look into the ./disks directory.

So you might put Hatari into the menu (/pandora/menu/Hatari131.pnd), or into the desktop (/pandora/desktop/Hatari131.pnd), or somewhere else. Regardless, the appdata will be (with the version I'm building now), /pandora/appdata/hatari.skeezix and thus you would put your .ST or .MSA disk images into /pandora/appdata/hatari.skeezix/disks to make them visible to the emulator. However, given it features its own UI, you can put them into /roms/atarist or /disks or whatever, and use them from there.

How Do I Make .PNDs?

Libpnd Hub has more information.

More Info About .PNDs

Visit libpnd_hub for more information!

Firmware

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.

The process for reinstalling the firmware is as follows: [2]

  1. Extract the contents of the zip to root (main) directory (folder) of your SD card. Fat32 and ext2 filesystems are supported.
  2. Make sure the pandora is turned off (remove the battery in case it crashes or doesn't turn off by using normal means).
  3. Insert that SD card into pandora's first slot(it's the one closer to headphone jack).
  4. Press and hold the right trigger ('R'), then turn the power on (if you have battery removed, insert it while holding R).
  5. A menu should appear on screen. Select "boot from SD1" using the d-pad by pressing B or X.
  6. Wait for flash process to finish. Connect the charger to be sure the battery doesn't run out while flashing. Press enter when asked to do so.
  7. The device should turn off, press power (without holding R) to turn it back on.
  8. It should then start it's first boot process which migh take up to 15 minutes, be sure to wait for it to finish, otherwise firmware corruption might happen again.

The first firmware release can be found here (Version: 2010-05-01-Zaxxon)

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

Pandora FAQ

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

Futher reading