Pandora Wiki - User contributions [en]

Compo4All

2014-09-23T20:07:38Z

Skeezix: /* Publishing a game to the servers */

Compo4All is an gaming competition system designed by Skeezix.

The initial system was based on a MAME build where highscores were uploaded to a website, but has since expanded to include native Pandora games ([[PND]]) as well.

== Platforms ==
Currently, the only supported platform is the Pandora, but there are thoughts about expanding it to the Raspberry Pi, and desktop environments.

There is an unofficial port of C4A for the GCW and Caanoo. However at the moment only a few games (no MAME) are supported yet.

== Launchers ==
* Skeezix's [http://repo.openpandora.org/?page=detail&app=compo4all-skeezix-0001 Compo4All MAME] ([http://boards.openpandora.org/index.php/topic/12127-release-compo4all-mame-ladderscoreboard-competition-for-classic-arcade-games/ Forum Thread])
* Skeezix's [http://repo.openpandora.org/?page=detail&app=compo4all-mgr-skeezix-0001 Compo4All Manager] ([http://boards.openpandora.org/index.php/topic/13742-c4a-manager-now-on-repo-beta-please-test-it-create-your-c4a-profile-without-using-c4a-mame-now/#entry260224 Forum Thread])
* [http://pandorawiki.org/User:Pmprog pmprog's] [http://repo.openpandora.org/?page=detail&app=thetournamenthub.marqwatkin Tournament Hub] ([http://boards.openpandora.org/index.php/topic/12745-pandora-compo4all-ui/ Forum Thread])
* Ziz's [http://repo.openpandora.org/?page=detail&app=Sparrow-C4A-Manager-1337 Sparrow C4A Manager] ([http://boards.openpandora.org/topic/14104-sparrow-compo4all-manager-and-puzzletube-c4a-edition-betas Forum Thread])

== Scoreboard ==
Scores are shown within the three launchers, but are also accessible via a web browser at [http://c4a.openpandora.org/ http://c4a.openpandora.org]

== Developers SDK ==

There are two ways of developing C4A stuff at the moment. First of all the official way from skeezix. Details of the official API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]].

The second way is to use libSparrowNet, an independent library from Ziz, which encapsulate the network stuff with background thread and multi platform support. Details can be found [[Using_C4A_with_libSparrowNet|here]].

== Publishing a game to the servers ==

Given that a game supports compo4all (pushes scores to it, say), a few steps remain.

- the compo4all server must be told about the game, via a config file submitted to skeezix (at the openpandora boards)
- ideally, the http://c4a.openpandora.org/ website needs to have some marquee artwork (send an image to milkshake at the openpandora boards)

A config file example (pulled from current indie game) is below; the values shoudl be more or less self explanatory, but I realize at this time this isn't a great deal of information; please ask if you're confused about the syntax or acceptible values and I'll update this page!

Sample config file:

{
"active": true,
"plugin": "scoreonly",
"module": null,
"alltime": true,
"platforms": [ "pandora" ],
"league": "all",
"shortname": "mygame",
"longname": "My Game!",
"ordering": "highest-first",
"dispunit": "points",
"type": "int",
"field": "indie",
"genre": "logic",
"execinfo": {
"pandora": {
"type": "standalone",
"pnd_unique_id": "mygame.skeezix.001",
"last_known_filename_hint": "mygame.pnd",
"command_line_add": "",
"last_known_appdata_hint": "mygame",
"file_dependancies_hint": ""
}
}
}

Permissible values..

ordering: lowest-first highest-first
type: standalone
league: all
field: indie arcade
genre: logic strategy racing action shmup runngun

Compo4All

2014-09-23T20:06:13Z

Skeezix: /* Developers SDK */

Compo4All is an gaming competition system designed by Skeezix.

The initial system was based on a MAME build where highscores were uploaded to a website, but has since expanded to include native Pandora games ([[PND]]) as well.

== Platforms ==
Currently, the only supported platform is the Pandora, but there are thoughts about expanding it to the Raspberry Pi, and desktop environments.

There is an unofficial port of C4A for the GCW and Caanoo. However at the moment only a few games (no MAME) are supported yet.

== Launchers ==
* Skeezix's [http://repo.openpandora.org/?page=detail&app=compo4all-skeezix-0001 Compo4All MAME] ([http://boards.openpandora.org/index.php/topic/12127-release-compo4all-mame-ladderscoreboard-competition-for-classic-arcade-games/ Forum Thread])
* Skeezix's [http://repo.openpandora.org/?page=detail&app=compo4all-mgr-skeezix-0001 Compo4All Manager] ([http://boards.openpandora.org/index.php/topic/13742-c4a-manager-now-on-repo-beta-please-test-it-create-your-c4a-profile-without-using-c4a-mame-now/#entry260224 Forum Thread])
* [http://pandorawiki.org/User:Pmprog pmprog's] [http://repo.openpandora.org/?page=detail&app=thetournamenthub.marqwatkin Tournament Hub] ([http://boards.openpandora.org/index.php/topic/12745-pandora-compo4all-ui/ Forum Thread])
* Ziz's [http://repo.openpandora.org/?page=detail&app=Sparrow-C4A-Manager-1337 Sparrow C4A Manager] ([http://boards.openpandora.org/topic/14104-sparrow-compo4all-manager-and-puzzletube-c4a-edition-betas Forum Thread])

== Scoreboard ==
Scores are shown within the three launchers, but are also accessible via a web browser at [http://c4a.openpandora.org/ http://c4a.openpandora.org]

== Developers SDK ==

There are two ways of developing C4A stuff at the moment. First of all the official way from skeezix. Details of the official API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]].

The second way is to use libSparrowNet, an independent library from Ziz, which encapsulate the network stuff with background thread and multi platform support. Details can be found [[Using_C4A_with_libSparrowNet|here]].

== Publishing a game to the servers ==

Given that a game supports compo4all (pushes scores to it, say), a few steps remain.

- the compo4all server must be told about the game, via a config file submitted to skeezix (at the openpandora boards)
- ideally, the http://c4a.openpandora.org/ website needs to have some marquee artwork (send an image to milkshake at the openpandora boards)

A config file example (pulled from current indie game) is below; the values shoudl be more or less self explanatory, but I realize at this time this isn't a great deal of information; please ask if you're confused about the syntax or acceptible values and I'll update this page!

Sample config file:

{
"active": true,
"plugin": "scoreonly",
"module": null,
"alltime": true,
"platforms": [ "pandora" ],
"league": "all",
"shortname": "mygame",
"longname": "My Game!",
"ordering": "highest-first",
"dispunit": "points",
"type": "int",
"field": "indie",
"genre": "logic",
"execinfo": {
"pandora": {
"type": "standalone",
"pnd_unique_id": "squared!.gandi",
"last_known_filename_hint": "squared.pnd",
"command_line_add": "",
"last_known_appdata_hint": "squared",
"file_dependancies_hint": ""
}
}
}

Permissible values..

ordering: lowest-first highest-first
type: standalone
league: all
field: indie arcade
genre: logic strategy racing action shmup runngun

Compo4AllSDK

2013-05-11T00:27:36Z

Skeezix: /* Getting the execution info */

= Compo4All API Guide =

== Overview ==

All information from the server is transfered by the HTTP protocol, so you can use libraries such as libcurl to handle all that work.
Information is passed using the JSON markup language

== Launcher Developer ==

=== Getting the Games List ===

Sending a HTTP GET request to [http://skeezix.wallednetworks.com:13001/curgamelist_1 /curgamelist_1] will return you a list of games, and details of those games

The JSON response will be an array of dictionairies (one dictionairy per game.)

The dictionaries will include at least the following fields for each game:
- gamename -> the 'short name' of the game; for MAME, it is the driver name ('dkong') and not generally for display; it is a unique-id (unique within C4A)
- longname -> the readable display name ('Donkey Kong')
- status -> current status options include:
- available -> show in frontends, available for scoring etc
- active -> show in frontends (and highlight or in their own tab?), is actively in the ROT tournament or highlight right now (but is otherwise same as available)
- wip -> do not show in frontend; available for scoring and functionality identical to 'active', but for developers to test their code prior to finalization
- genre -> the 'type' of game (at a high level); current values are..
- platform
- maze
- runngun
- shmup
- strategy
- ... we can add more - to be determined
- field -> the 'kind' of game it is, the platform; current values are
- arcade -> implies c4a-mame will be used
- indie -> means standalone; it will contact c4a, but not be part of c4a-mame
- TBD

=== Getting the Score Board ===

Requesting [http://skeezix.wallednetworks.com:13001/json_1/bublbobl /json_1/(gamename)] will return you scoreboard details

- You can also pull a simple HTML (ASCII) dump: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/
- Getting previous months can use backdating for both JSON and ASCII pulls; for example: skeezix.wallednetworks.com:13001/scoreboard_1/mspacman/201304/

The scoreboard is an array of dictionairies, one dict per score entry.

The dictionairies will include at least:
- shortname -> the player's shortname (initials)
- longname -> the player's long name (display name)
- hi -> the actual score number (for single-score style of games); TBD for time-attack, and other kinds of games
- time -> the epoch time the event occured

=== Getting the execution info ===

The execinfo request will get you some details so you can actually run the application needed for a given game. The url form is:

Example: skeezix.wallednetworks.com:13001/execinfo_1/microbes/pandora

Example return:
- command_line_add": ""
- "file_dependancies_hint": "",
- "last_known_filename_hint": "microbes1.0rel2-1.pnd"
- "pnd_unique_id": "microbes.wb.mainapp"
- "type": "standalone"
- "last_known_appdata_hint": "microbes"

File dependancies could be things like "roms/dkong.zip" for a MAME dependancy, say.

Command line add could be: "--c4a --game foo" or whatever the application needs to tell it we're running from a c4a frontend.

The actual invocation could be done a number of ways, such as by using pnd_run or pnd_run.sh directly; you can use libpnd (built into the firmware) for all the heavy lifting .. it has utility functions for most everything you need.

Some quick off-memory pseudocode follows-- though its so close it would nearly compile:

<code>
Now, libpnd gives you everything you need to run stuff, but you have to call a few functions.. its not all rolled into one.

Why?

Because it lets you be efficient; your steps are usually..
i) Ask it to find pnd_run.sh <- you can skip it, and use the firmware path if you want
ii) Ask it for a path set from config <- you can skip it, hardcode it if you like: the fw conf is:
/media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps
- you feed that to the discovery function
iii) Ask it to run a discovery (return all apps within a path set)
--> keep this value; it returns a 'box', a linked list, save it so that you don't have to re-discover for every run; discover once, and then you are run-instantly next run
iv) for loop over the result list, looking for unique-id match
v) ask libpnd to run the entry you found (just pass the box pointer into the run function)

Its pretty easy for me anyway :) All you need is steps 3-5.

If I roll you a utility 'run the damned pnd' function, it'll be doing all that stuff every time... pretty inefficient.

The code would be like this:

Given char *my_unique_id that you know from the server.

#include "pnd_pxml.h"
#include "pnd_utility.h"
#include "pnd_conf.h"
#include "pnd_container.h"
#include "pnd_discovery.h"
#include "pnd_apps.h"

// run a discovery
pnd_box_handle g_active_apps = NULL;
char *searchpath = "/media/*/pandora/apps:/media/*/pandora/desktop:/media/*/pandora/menu:/usr/pandora/apps" <- from conf file!

g_active_apps = pnd_disco_search ( searchpath, NULL ); <- keep this value for the life of the frotnend session

if ( ! g_active_apps ) {
printf ( life is hell )
return ( sucks )
}

pnd_disco_t *a = pnd_box_get_head ( g_active_apps );
void *nexta = NULL;

while ( a ) {
nexta = pnd_box_get_next ( a );

if ( strncmp ( a -> unique_id, my_unique_id, strlen ( my_unique_id ) ) == 0 ) {
// found disco-t entry, run it

ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, 0 /* options */, NULL );
if ( ret ) .....

}

a = nexta;
}

..

Thats it :)

Now, the pnd_run.sh path might be wrong, I dont' sleep much :)

....

Now, you want to pass args.. theres some params to pnd_apps_exec_disco() so you can pass it args, I think:

pnd_apps_exec_info_t extra;
extra.args = "--game foo"
then pass PND_EXEC_OPTION_INFO into the 'args' bit instead:

ret = pnd_apps_exec_disco ( "/usr/scripts/pnd_run.sh", a, PND_EXEC_OPTION_INFO /* options */, &extra );

That should do it, but I'm going from memory. Still, thats pretty damned close pseudo-code... probably compiles ;)
</code>

== Game Developer ==

=== Spaghetti Client ===

The [http://boards.openpandora.org/index.php/topic/12127-release-compo4all-mame-ladderscoreboard-competition-for-classic-arcade-games/page-18#entry237182 Spaghetti Client] can be downloaded from the thread, and you can easily submit scores by starting a process with the following command line (assuming sc is bundled in your working directory)

The paramater's vary by module;

An example for the 'scoreonly' simple module is:
<source lang="bash">./sc MODULE OPERATION GAMENAME PLATFORM SCORE</source>

Platform: Currently 'pandora' should be specified

==== SC Modes ====
{| border="1"
|-
! Mode
! Description
|-
! so
! Sends the Score only
|}

==== SC Operations ====
{| border="1"
|-
! Operation
! Description
|-
! push
! Sending data to the server
|-
! pull
! Get data from the server (not implemented)
|}

==== SC Exec Return Values ====
{| border="1"
|-
! Value
! Description
|-
! 0
! All seemed well
|-
! -1
! General error (such as bad arguments to sc); maybe failure to get RAM; possibly a problem with plugins (scoreonly module submissions.)
|-
! -2
! Could not write file that was pulled; coudl not find player profile
|-
! -3
! For a file dependancy (such as MAEM ./hi file), file could not be found/opened
|}

Compo4AllSDK

2013-05-11T00:27:08Z

Skeezix: /* Minimenu - Comprehensive Configuration Documentation */

<div style="border-top:1px solid gray; border-bottom:1px solid gray; padding-top:5px; padding-bottom:5px; margin-bottom:20px">     ''This page is an unofficial community project, and Open Pandora Ltd. is not responsible for its content.''</div>

[[Image:PandoraFront.jpg|Right|thumb|360px|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 [http://www.gp32x.com/board/index.php?/forum/61-pandora/ 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). [[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)
The following items should also be present if you ordered them separately:
*TV-Out Cable
*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**

:<small><nowiki>*</nowiki>The 600Mhz+ can be higher or lower. This can be controlled by software designed for the device.</small>
:<small><nowiki>**</nowiki>Is affected by use. (example turn bluetooth on or off during play time)</small>

==== 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 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:

# If you don't have a domain you want to connect to, simply enter any name here. It should not contain any spaces.
# 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{{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:

# The double-click Time setting
# 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.

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

==== The File Manager ====
==== Killing Applications ====
==== 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
* "vi <filename>" - Opens the file for editing in vi [http://pandorawiki.org/Vi]

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

*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' [http://dl.openhandhelds.org/cgi-bin/pandora.cgi Pandora File Archive].

*There are nice repositories, such as the [http://www.angstrom-distribution.org/repo Angstrom ARM Repository], or...

*The Pandora includes the package manager [http://en.wikipedia.org/wiki/Ipkg ipkg].

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

<div style="border-top:1px solid gray; border-bottom:1px solid gray; padding-top:5px; padding-bottom:5px; margin-bottom:20px">     ''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).''</div>

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

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

<source lang="c">
[Application-0]
title HatariHack0
maincategory Audio
maincategorysub1 Emulator
[Application-1]
title HatariHack1
clockspeed 200
note-1 My text for note line 1
</source>

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.

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

==== How Do I Make .PNDs? ====
==== 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 ;)

==== Setting Up WiFi ====
==== Setting Up Blutooth ====
==== Adjusting Brightness/Contrast ====
==== Changing Your Theme ====
== Minimenu - Comprehensive Configuration Documentation ==

=== Interesting Menu Items for General Usage ===

==== Force all preview caching now ====

TBD

=== Default configuration is.. ===

* Runs without X, and with X.
* Look for applications in the Pandora normal places; your SD cards, in /pandora/desktop and /pandora/menu and /pandora/apps
* Look for additional apps in /pandora/mmenu (say, if you want to have minimenu-only applications, for some reason)
* Look for skins in /etc/pandora/mmenu/skins (on Pandora), but also in SD in /pandora/mmenu/skins/ -- so you can develope skins, or download them and drop them there on your SD.
* Will show pnd-applications in their Main Category tab, and in their Main Sub Category 1 tab. (But not in Main Sub 2, or Alt Category, Alt Sub 1, or Alt Sub 2)
* Will show an "All" tab
* Will show a tab for each non-empty directory in /media -- ie: your SD cards (or USB devices, or other mounts)
* Will not wrap tabs -- when you hit right-trigger to switch to the next right tab, and there are no more, it won't go to the first tab
* Will use DaveC's skin
* Will load application icons when the menu starts up (its pretty fast, so this is usually okay)
* Will load preview pics after the selection rests on an application in the grid for a second or two (ie: not on startup, since it is _very slow_)
* Will try to cache preview pics onto SD card (firstly on the same SD as the application, but will also search other SDs/devices until it finds one with at least 500KB free space)
* Will load preview pics in real time (make you wait while it loads, not do it in background while you do other stuff.)
* Will scroll whole page of the grid up and down
* Will wrap around left/right of grid, staying on same row
* Will wrap around top/bottom of the grid
* Will look for 'category conf' file in /pandora/mmenu on your SDs as mmcatmap.conf; most people will never create this file

=== Global/User Preferences ===

Minimenu will search for mmenu.conf in a sequence of locations, so that you may override it without clobbering the built in system defaults.
# /pandora/mmenu/mmenu.conf - so you can override it on your SD cards
# /etc/pandora/conf/mmenu.conf - the system default
# ./minimenu/mmenu.conf - so you can run from 'current directory' while doing development. Most people can ignore this.

Options in minumenu are broken up into config file sections.

Most options have internal defaults, but many do not, so the conf files are needed; if you break a conf file, it will often still work.. but you can make minimenu crash, so be careful and keep conf file backups. It is probably wise to edit conf files via the override on SD cards, and put skins on SD cards, so that worst case.. pop out your SD and you're good to go with default system again.

==== [minimenu] section ====

* skin_searchpath -- defines the directories that will be searched to find skin-directories. A skin directory is a _directory containing mmskin.conf_ so searchpath may include /media/*/pandora/mmenu/skins to mean that SD cards will be searched in /pandora/mmenu/skins - a skin named "Foo" will then be /pandora/mmenu/skins/Foo/ and contain mmskin.conf
* skin_selected -- defines where to store the name of the activated skin; if this file does not exist, or the named skin cannot be found, the skin named 'default' will be searched for in skin_searchpath
* skin_confname -- the name of the conf file to look for in skins; if you change this, everything will break :)
* load_previews_new -- if set to >0, will attempt to load preview pics _at startup of menu every time_ -- EXTREMELY SLOW for un-cached previews; if, however, you have recently done a "force cache all previews", and thus are fully cached, it might not be too bad. Highly unadvisable.
* load_previews_later -- if set to >0, will want to load preview pics later; if set to 0, will not even try to load preview pictures, ever.
* load_icons_later -- if set to >0, will attempt to load icons after menu starts; normally set to 0, meaning load icons during menu startup (advisable, since its pretty fast.)
* defer_icon_us -- when load_icons_later is activated, this is the microseconds delay between loading icons. (ie: background thread will load icon, then another icon, then another .. with this delay between)
* threaded_preview -- if set to >0, will load preview pics in background; not advisable. Normally will make you wait while preview happens. First releases of Pandora will probably take a few seconds to load each preview, and doing it in background chugs the user experience too much. (A later improvement to pnd_run.sh or creating a fast-mount script that skips the Union Filesystem Mount will make preview loading MANY times faster, at which point this might be a good option.)
* loglevel -- if you wish to turn up or down the logging
* x11_present_sh -- define the command used to figure out if X is present or not; some apps require X, or require no X, or don't care; the menu may decide to filter out apps depending on their requirements and whethor X is running or not
* desktop_apps -- if set to >0, will look in the desktop searchpath for apps (/pandora/desktop say; see /etc/pandora/conf/desktop)
* menu_apps -- if set to >0, will look in menu searchpath too -- see /etc/pandora/conf/desktop
* aux_searchpath -- if you wish to look somewhere else for applications entirely (such as for minimenu specific apps? or another pile of apps?) then look in this searchpath

==== [utility] Section ====

* terminal -- specifies the command to run when the Select menu is used and user requests to run a Terminal; ie: you could set it to Xterm, or Konsole, or Terminal, or whatever you prefer.

=== Setting up Category Mapping/Merging/Aliasing and Custom Tabs ===

=== Skinning the Interface ===

==== Setting up a skin you download ====

==== Creating new skins ====

== 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!
==== Restore The Original Firmware ====
==== Boot From SD or USB ====

== Pandora FAQ ==
Silly goose, go to the [[FAQ]] page for more detailed information.

[[Category:Categories]]

User manual

2010-04-06T17:21:06Z

Skeezix: /* Oops! I Borked My Pandora! */

PXML specification

2010-03-26T15:48:30Z

Skeezix: /* Description */

'''Attention:''' at the present time, the PXML file format isn't set in stone, and is therefore subject to change. There is no guarantee that the format or the schema are bug-free or will be changed at any time. Please wait until this standard is finished before writing a PXML file.

This is the human-readable specification for the PXML file format. The PXML file format is used in your applications for the OpenPandora® that you package in ".pnd"-files or distribute otherwise, to make it possible for menus and launchers to use your applications and their properties.

A PXML file should be appended to your ".pnd"-file, using the tools provided for that purpose, or put in a directory that you want to serve as a redistributable package, to make it possible for launchers and menus to find it. It should have the name "PXML.xml" not case sensitive, and there should only be one such file. The contents of the PXML file should also comply to this specification without exception, to guarantee that everyone will be able to read it.

== XML compatibility ==
The PXML format is XML-based and fully XML-compliant, which means that it can be read and written by any XML reader or writer. Included with this specification should also be a ".xsd"-file, which is used by XML tools to validate PXML files. A ".xsd"-file is also known as a XML schema, and can be called the "computer-readable" version of this document. It is very good practice to validate your PXML-files with that schema before publishing them.

To write a PXML file, you also need to know the basics of writing a XML file. It boils down to the following:

# If an element contains text or other elements, it needs a start-tag and an end-tag. This looks like (1)
# If an element does not contain other elements or text, but only attributes, it looks like (2)
<source lang="xml">
<exampleelement someattribute="something">something inside it</exampleelement> 
<exampleelement2 someattribute="something" /> 
</source>

== Format ==

The PXML-file is split up into multiple so-called elements, each of which specify one property of the ".pnd"-package. All of these elements are surrounded with a "<PXML>"-tag, which tells the readers of the file that the data within that tag belongs to a PXML file. The tag and elements should be defined as follows:
=== The PXML-tag ===
==== Description ====
The PXML-tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file. An example "<PXML>"-tag would look like this:

<source lang="xml">
<PXML xmlns="http://openpandora.org/namespaces/PXML" id="uniqueID">

</PXML>
</source>

As you can see, the PXML tag accepts a few attributes, namely the "id" and "xmlns" attributes.

* The "xmlns" attribute is required by the XML standard, and guarantees that this file will be identified as a PXML file. You must include the xmlns attribute, exactly as shown, in your PXML file, with the URL as specified. Only then can it be guaranteed that the file will be read at all by launchers and menu apps.
* '''DEPRECATED; SEE "application" tag.''' The "id" attribute specifies an identifier for your PND package, and should be something globally unique so that no two PND packages have the same id. This can be achieved by appending some random number to your application name, and to use that as your id; or to simply generate a completely random, very long id. If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur. Please put effort into generating an unique id for your PXML-file.

=== The Application-tag ===
====Description====
The Application-tag permits the PXML.xml container to have multiple applications within it; you should have at least one application tag-pair (for one app), though you may have many.

<source lang="xml">
<application id="uniqueID" appdata="dirname">

</application>
</source>

* The "id" attribute specifies an identifier for your PND package, and should be something globally unique so that no two PND packages have the same id. This can be achieved by appending some random number to your application name, and to use that as your id; or to simply generate a completely random, very long id. If this id already is used in another PND file, those two PND files will conflict with each other, and unforseeable errors will occur. Please put effort into generating an unique id for your PXML-file.

* The "appdata" permits a directory name (NOT PATH) to be specified as preferred; if not present, the unique-id will be used. For example, we may want a unique-id of "Battlejewels.skeezix.3216836217382163.v001", but a appdata path of "battlejewels" to make it easier on the user, or to have multiple different battlejewels sharing one appdata.

A good unique-id is the application name, developer name, and some key you may wish to update on occasion (should state-data become incompatible between updates, say.)

Consider:
battlejewels.skeezix.001
quake-1.pickle.001

unique-id formatting: '''Should not include directory or filename invalid characters, such as ?, >, /, etc. Any of those will cause the pnd-file to not function.'''

Note on Uniqueness: The unique-id should be unique against other pnd-files, but may be re-used by other 'application' tags within the pnd; for example, you may have multiple subapps that want to share the same appdata path (which is formed based on unique-id!), so use the same unique-id. You might then have a utility application in that same pnd, which needs its own appdata, and so gets its own unique-id.

=== The title element ===
==== Description ====

The title element specifies the text that is shown to the users of your PND file as the application title. This element can be specified multiple times in multiple languages (the language is indicated by the lang attribute).

At least one "title"-element is required, in the "en_US" American English language.

==== Example ====
<source lang="xml">
<title lang="en_US">Your application name</title>
<title lang="de_DE">Dein Programmname</title>
</source>

=== The description element ===
==== Description ====

The description element specifies the text that is shown to the users of your PND file as the application description. This element can be specified multiple times in multiple languages the language is indicated by the lang attribute.

At least one "description"-element is required, in the "en_US" American English language.
==== Example ====
<source lang="xml">
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</source>

=== The exec element ===
==== Description ====

The exec element should specify all the information needed to execute your application.
An exec element must be included in every PXML file. It accepts the following attributes:

* The command attribute specifies the path to the executable file. This should be a relative path to a file within the PND package. Must contain no arguments! One strategy you may need is to point to a sh-script in your pnd-file, which in turn sets up LD_LIBRARY_PATH, determines arguments to pass, uses zenity to pop up a pre-run menu, or other trickery.
* The arguments attribute may be not present, or present with 1 or more arguments to the executable.
* The startdir attribute specifies the starting directory (Also known as the working directory) that the application should start in. This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.
* The standalone attribute specifies whether or not this application can run on its own, or if it needs parameters to run. A value of "true" or "1" means that the application can be run without parameters. A value of "false" or "0" means that the application must be run with parameters (Meaning that no icon will appear for it in a launcher; it will only be run via file associations or via the terminal).
* The background attribute specifies whether or not this application should run in the background, and it should be possible to switch to other apps while it is running, or if it is the only application that should be running. A value of "true" or "1" means that the application can run in the background. A value of "false" or "0" means that the application must be run as the only application.
* The x11 attribute may be missing; values are one of "req", "stop", and "ignore". If "req" is set, it means the application requires X11 (and possibly could be filtered out of users display in a menu if X is not running, or perhaps such a menu would have to start X.) If "stop" is set, it means X must be not running, or temporarily shut down, for the app. If "ignore" is set, the app doesn't care if X is running or not (such as an SDL app, or a sh-script, etc.)

==== Example ====
<source lang="xml">
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="myprogram" arguments="arg1 arg2" x11="option"/>
</source>

=== The icon element ===
==== Description ====

The icon element should specify a nice icon for your program.
An icon element is optional. It accepts the following attributes:

* The src attribute specifies the path to the image file used as the icon.

NOTE: Current implementation will use the pnd-file's appended icon; for a PXML-app-directory, it will try to use the icon mentioned in the PXML. So for a pnd-file, all subapps will show the appended-icon, regardless of the <icon> tag within the PXML.xml

==== Example ====
<source lang="xml">
<icon src="images/icon.png"/>
</source>

=== The info element ===
====Description====

The "info" element allows the PXML.xml to suggest to the desktop environment or menu a file that may be shown to the user when they want to know more - be it an About, a Install Guide, a User Guide, or all of the above.

The file can be a txt-file or an html-file, and as the PXML-app-dir or .pnd-application will be mounted, the file may in turn branch to other files should it wish to.

Developers do not need to have this element, if their app is nice and simple and just runs. If the application requires additional set up (such as Quake requiring separate pak files that cannot be included in the pnd), or if you wish to include sample config files or config guidelines for something complex like DosBox, or include Pandora-specific notes.. those are all good things. But the developer is encouraged to be tasteful and not go hog-wild!

* name → the name to be shown in the menu; should be obvious that it belongs to the pnd .. Quake's game pnd could have "Quake 1 Setup".
* type → the mime type for the file; in the event the consuming application can map mimetypes to an appropriate executable, this would be a good way of letting the user's preferred reader come up. Should be one of "text/html" (for an html file) or "text/plain" (for a .txt file)
* src → '''required''' A file (including path relative to the pnd; ie: ./index.html would be the root of the pnd) in the pnd to open up; by default, the web browser will likely be used to open it.

==== Example ====
<source lang="xml">
<info name="AwesomeGame Setup" type="text/html" src="index.html"/>
</source>

=== The previewpics element ===
==== Description ====

The previewpics element is an element that contains multiple other elements.
A previewpics element is optional.

It contains multiple pic-elements. Every pic-element represents one preview picture. If the previewpics element is specified, it must contain at least one pic element.

* The src attribute on a pic element specifies the path to the image file used as the preview picture.
==== Example ====
<source lang="xml">
<previewpics>
<pic src="preview/pic1.jpg"/>
<pic src="preview/pic2.jpg"/>
</previewpics>
</source>

=== The author element ===
==== Description ====

The author element is an element that is used by the author to introduce him/herself.
An author element is optional. It accepts the following attributes:

* The name attribute specifies the name of the author.
* The website attribute specifies the website of the author.
* The email attribute specifies the e-mail of the author. This attribute is not yet supported by libpnd, but please specify it anyways.
==== Example ====
<source lang="xml">
<author name="Bjornhild Andersson" website="http://some.website.with.author.info"/>
</source>
=== The version element ===
==== Description ====

The version element specifies the application version.
A version element is required. It accepts the following attributes:

* The major attribute specifies the major version number. This number should be 0 or more.
* The minor attribute specifies the minor version number. This number should be 0 or more.
* The release attribute specifies the release number. This number should be 0 or more.
* The build attribute specifies what build the application is at. This number should be 0 or more.
==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2"/>
</source>
=== The osversion element ===
==== Description ====

The osversion element specifies the minimal OS version that supports the PND file. The PND file will not be loaded by an OS that has an older version than the one specified here.
An osversion element is optional. It accepts the same attributes as the version element.

==== Example ====
<source lang="xml">
<osversion major="1" minor="1" release="1" build="2"/>
</source>
=== The categories element ===
==== Description ====

The categories element is an element that contains multiple other elements.
A categories element is required, and must contain at least one category.

Menus that use your PXML in any shape or form will use the category information to sort your application entry into the tree or sub menus. Depending on the menu system, this will be done differently every time. It is therefore advisable to specify as many categories and subcategories as possible (and as suitable; don't specify that your application belongs in a category if it doesn't).

The "categories" element contains multiple category-elements. Every category-element represents one category that this app can be sorted into. Valid top-level categories are (among others):

# AudioVideo
# Audio
# Video
# Development
# Education
# Game
# Graphics
# Network
# Office
# Settings
# System
# Utility

Please see [http://standards.freedesktop.org/menu-spec/latest/apa.html the FreeDesktop specification] for more information. In it, you will also find valid subcategories for your top-level categories.

The category-element takes one attribute: The name-attribute. This attribute represents the category name, which preferrably should be one of the above.

A category-element can contain further child-elements: subcategory-elements. These represent the subcategories of a category that the app will be sorted into.

The subcategory-element also takes a name-attribute; this attibute can contain a name for your subcategory.

==== Example ====
<source lang="xml">
<categories>

<category name="Game">
<subcategory name="StrategyGame"/>
</category>

<category name="Graphics">
<subcategory name="ImageProcessing"/>
</category>
</categories>
</source>
=== The associations element ===
==== Description ====

The associations element is an element that contains multiple other elements.
An associations element is optional, except if exec.standalone is false.

It contains multiple association-elements. Every association-element represents one file action association.

* The name attribute on an association element specifies the user-friendly action name for the association.
* The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.
* The exec attribute on an association element specifies the command-line arguments that should be given to the program, when this action is performed. The exec can contain a "%s", which indicates where the file name of the file, that the action is performed on, should be inserted. For example, if the exec-line is "--file %s --type lol", and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into "--file "lol.bmp" --type lol"
==== Example ====
<source lang="xml">
<associations>
<association name="Deinterlaced Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/>
<association name="Style sheet system crasher" filetype="text/css" exec="-f %s --crash-on-success"/>
</associations>
</source>

=== The clockspeed element ===
==== Description ====

The clockspeed element specifies what clockspeed this app should run at. Please do only specify this element if your application *needs* to run at the specified clock speed.
A clockspeed element is optional. It accepts the following attributes:

* The frequency attribute specifies the wanted frequency, in megahertz (MHz).

==== Example ====
<source lang="xml">
<clockspeed frequency="600"/>
</source>

=== The mkdir element ===

==== Description ====

The PXML may request creation of directories on the SD card.

'''This should be used sparingly.'''

There are a number of scenarios in which this may be useful; should an application wish to attempt to establish a canonicle location for a file, it can request a path be created. This can avoid user confusion -- user merely plugs in SD, waits a few moments, pulls out SD, and inspects it to see what directories he may populate. Consider 'id' files for Quake -- the user might have many ports of the game, such as Quake, or ioquake, or others. They could all share the same id pak files, but the user may not know where to put them. (Especially since the pnd-file itself does not have user documentation available perhaps.) Consider ROM-paths for emulators .. perhaps the emulator expects ROMs in a specific location? If so, the author may wish to have that location created, to make it obvious.

'''NOTES'''
The paths are created on the SD that contains the pnd.
The paths may not include ".." or wildcards.

It accepts the following attributes:

* dir -> the name of the path to be created; it may not be multiple levels deep - to effect that, include multiple <dir path="..."/> entries

==== Example ====
<source lang="xml">
<mkdir>
<dir path="/foo/bar"/>
</mkdir>
</source>

If this is in /pandora/desktop on SD1 (/media/mmcblk0p1 say), then /media/mmcblk0p1/foo/bar will be created.

== Example file ==
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PXML xmlns="http://openpandora.org/namespaces/PXML">

<application id="youruniqueID">

<title lang="en_US">Program Title</title>
<title lang="de_DE">German Program Title</title>

<exec background="true" command="program"/>

<info name="AwesomeGame Setup" type="txt/html" src="index.html"/>

<icon src="program.png"/>

<description lang="en_US">This is the English Description of the file.</description>
<description lang="de_DE">This would be the German description.</description>

<previewpics>
<pic src="preview/pic1.jpg"/>
<pic src="preview/pic2.jpg"/>
</previewpics>

<author name="Some Dudeson" website="http://a.bc.de"/>

<version major="1" minor="1" release="1" build="2"/>
<osversion major="1" minor="0" release="0" build="0"/>

<categories>
<category name="Game">
<subcategory name="StrategyGame"/>
</category>
<category name="Graphics">
<subcategory name="ImageProcessing"/>
</category>
</categories>

<clockspeed frequency="600"/>

</application>

</PXML>
</source>

== Validation ==

To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it.

You will also need to put the XML schema for the PXML format in the same folder as your PXML file. Note that the current PXML schema is horribly out of date.

When you have done that, and know how to use it, you need to change a few things in your PXML file. In your PXML tag, change the contents from this...
<source lang="xml">
<PXML xmlns="http://openpandora.org/namespaces/PXML"> ...
</source>

...to this:
<source lang="xml">
<PXML xmlns="http://openpandora.org/namespaces/PXML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="PXML_schema.xsd"> ...
</source>

Now the PXML file can be validated.

[[Category:Development]]