Pandora Wiki - User contributions [en]

Keyboard

2013-12-20T07:17:55Z

Edlee:

[[Image:Pandkey.png|thumb]]

In the months before the first preorders were taken, there was much discussion and community voting about the best layout. [http://www.gp32x.com/board/index.php?/topic/43762-pandora-keyboard-layout/ This] was one of the final votes. The final layout was different from either one of the two most popular community proposals, but incorporated some of the suggestions such as having a "Pandora" button.

Many desirable applications require a keyboard,general consensus was that an on-screen keyboard wasn't good enough. For computing mode, the game controls are used for mouse, cursor and control keys.

Some classic systems such as the Atari and C64, which had keyboards, are far more comfortably emulated on a device with a keyboard.

==Hotkeys==
'''alt+ctrl+ up / down''' | switches between virtual desktops. (if you put them in a single row in the widget you can use ← →) 
'''powerbutton slidelock left''' | locks keyboard nubs L and R shoulderbuttons 
'''pandorabutton + start''' | brings up a dialogue to kill processes

==Keycodes==
This table might be useful if you're trying to map keys in some program, or writing a program:
{| class="wikitable"
!Pandora button!!Keycode!!Hex Equivalent
|-
|Space || key 32 || 0020
|-
|Pandora || key 147 || 0093
|-
|D-pad up || key 273 || 0111
|-
|D-pad down || key 274 || 0112
|-
|D-pad right || key 275 || 0113
|-
|D-pad left || key 276 || 0114
|-
|Game A || key 278 || 0116
|-
|Game B || key 279 || 0117
|-
|Game Y || key 280 || 0118
|-
|Game X || key 281 || 0119
|-
|Shoulder L || key 303 || 012f
|-
|Shoulder R || key 305 || 0131
|-
|Select || key 306 || 0132
|-
|Start || key 308 || 0134
|}
Sources: [[DOSBox#Assigning_action_keys_to_A.2FB.2FX.2FY|1]], [http://www.gp32x.com/board/index.php?app=forums&module=forums&section=findpost&pid=949070 2], [http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__905644 3] [http://www.gp32x.com/board/index.php?/topic/55124-remapping-the-mouse-buttons-etc/page__view__findpost__p__896576 4] (note: the last two links give different keycodes for the gaming buttons. Possibly both numbers will work?){{FIXME|Check the keycode issue}}

== Matrix ==

The matrix layout is detailed on p.20 of the Hardware hacker's guide ([http://www.openpandora.org/downloads/PANDORA_Hackers_manual_v100.pdf here]). A more readable version appears below. A .svg version of the Pandora's keyboard layout (made by cosurgi) can be downloaded [http://www.mediafire.com/?8s157q5qj8dibjq here]. (broken link) {{FIXME|This should be embedded within this wiki. Also, that link is broken.}}

<gallery widths=250px>
Image:Final Keymat.jpg|the mat
image:Keypadmatrix.png
</gallery>

==Remapping keys on the keyboard==
First, an apology - I'm writing this without knowing how to remap the keys on the [[keyboard]], so this is not really a tutorial. It is currently just a collection point for information on the subject.

===Reference===
Forum Threads
* [[http://www.gp32x.com/board/index.php?/topic/55124-remapping-the-mouse-buttons-etc/ Remapping The Mouse Buttons, Etc?]]
* [[http://www.gp32x.com/board/index.php?/topic/54077-changing-the-function-of-buttoms/ Changing The Function Of Buttoms]]
* [[http://www.gp32x.com/board/index.php?/topic/54324-remap-gaming-buttons-within-xfce Remap Gaming Buttons Within Xfce]]

The os should allow the standard keypad and modifier keys to be defined to generate any key. So if you want shift '1' to be anything other than 'section', it is possible. somehow :(

===Linking events to Keys===
There is a Pandora event map daemon, which reacts to the lid close, Pandora button and power button.
It can be configured using the <pre>/etc/pandora/conf/eventmap</pre> file. How to reference additional special keys is TBD. A thread showing an example is [[http://www.gp32x.com/board/index.php?/topic/54944-xfce-style-changing-with-brightness-buttons-hack/ here]]
It is also possible to configure xfce to capture events (forum thread is not locatable today)

===Using shoulder buttons for mouse===
{{hint|Seems only to be reported working permanently on HF4 but see NOTE below}}
As described in this [http://www.gp32x.com/board/index.php?/topic/55124-remapping-the-mouse-buttons-etc/page__view__findpost__p__896576 post]
# Find the keycodes which you want to modify. Run '''xev''' (this needs to be installed from angstrom repo) from the terminal, and record the numbers.
# Edit the '''.pndXmodmap''' file in your home directory, modify or add (in the correct numerical order for ease) lines like this (for the shoulder buttons)
<source lang="bash">
keycode 62 = Pointer_Button1 NoSymbol Pointer_Button1
keycode 105 = Pointer_Button3 NoSymbol Pointer_Button3
</source>
# If you want to use the 'a' and 'b' buttons, the codes are 110 and 115 respectively.
# As a test, open the XFCE Accessibility settings and enable mouse keys.
# To make this permanent, download a compiled version of [http://urjaman.dyndns.info/xkbset xkbset], copy to /usr/bin and chmod a+x /usr/bin/xkbset
# Create a script (file) with this as content
<source lang="bash">#!/bin/sh
xkbset m
xkbset exp =m</source>
# Now open a terminal where the file is saved, and give it executable permissions:
#:<source lang="bash">chmod +x nameofyourfile.sh</source>
#Now install it:
#:<source lang="bash">sudo cp nameofyourfile.sh /usr/bin/nameofyourfile</source>
# Add this script to XFCE autostarted stuff (Session and Startup->Application Autostart)
NOTE
# For HF5 you only need add these two commands to .xinitrc (located in your home directory)
<pre>xkbset m
xkbset exp m</pre>
note the missing =(equals) sign

===Swapping Caps Lock and Tab===
As a command line junkie, I was pretty frustrated with where Tab is. I decided to remap it to where Caps Lock is (Fn + Shift). I added the following to .pndXmodmap (in your home directory):
<pre>keysym Tab = Caps_Lock
remove Lock = Caps_Lock
keycode 66 = Tab NoSymbol Tab
add Lock = Caps_Lock</pre>
After you add this, just run "xmodmap ~/.pndXmodmap" to reload the keymappings

== Keyboard layout changer tool ==

The '''keyboard layout changer''' provides a means to easily change keyboard layout. Possible uses are for typing in a different language on your Pandora, for using an external keyboard, or simply for making small key modifications.

=Usage guide=
#Download the PND to your Pandora from either [http://stuffs.slaeshjag.org/pnd/kblayout.pnd Slaeshjag's site] or from the [http://repo.openpandora.org/?page=detail&app=change-keymap-0.1-slaeshjag Repo] (see [[User_manual#Installing_a_PND_file_.28an_application.29|here]] for instructions on where to place PNDs)
#Run the PND; it's called "Keyboard Layout" and is in the "Settings" category
#You will now see a choice of keyboard layouts. Choose one, and your layout will change! (if the program doesn't run, find the <code>/tmp/pndrun_kblayout.out</code> file and post its contents in the [http://boards.openpandora.org/index.php?/topic/2428-keyboard-layout-changer/ official forum thread], so that the author can see what went wrong)

==Keyboard layouts==

[http://repo.openpandora.org/?page=detail&app=change-keymap-0.1-slaeshjag Keyboard layout] is an app by slashjag which helps you change layout in a graphical interface.

=== Make your own ===

*Go to the <code>/media/yourSDcard/pandora/appdata/kblayout/keymaps</code> directory. Inside, you will see a bunch of files. Open any one with a text editor, and you'll see something like this:

./setxkbmap -layout us
xmodmap ~/.pndXmodmap

What this means is that it's using the "us" layout with the modifications specified in the ".pndXmodmap" file (the Pandora needs these modifications because its keyboard isn't the same as a standard one).

So there are two basic things you could change: you could replace "us" with a different base layout, or you could replace "~/.pndXmodmap" with a different file.

===Base layouts===
The default layout is "us". The full list of base layouts included with the Pandora is listed in the file <code>/usr/share/X11/xkb/keymap/xfree86</code>. Here's the full list:
{{HideableNotes|<pre>
us
ar
be
bg
br
cz
de
ch_de
ch_fr
dk
dvorak
en_US
es
fr
fr-latin9
fr_CA
gb
hr
it
jp106
lt
lt_std
lv
mk
mt
no
pl
pt
ro
ro_microsoft
ru
se_FI
se_SE
sl
sl_SI
sk
syr
th
th_tis
th_pat
tr
uk
us_flexpro
us_intl
us_microsoft
uz
cz_qwerty
de_CH
fr_CH
mt_us
sk_qwerty
</pre>}}

If you just want to use one of these base layouts with no modifications, make a new file in the <code>/media/yourSDcard/pandora/appdata/kblayout/keymaps</code> directory, name it anything, open it in a text editor and place the following text inside, replacing "xx" with any of the codes in the above list:
./setxkbmap -layout xx
Save the file. Then just start Keyboard Layout Changer, and you'll be able to select it.

===xmodmap===
This type of file modifies whatever base layout is selected. One of these comes by default with your Pandora OS. You can find the <code>.pndXmodmap</code> file in the <code>/home/username</code> directory. It might be hidden, so press Ctrl+H to make it visible. If you open it with a text editor, you'll see this:

{{HideableNotes|<pre>keycode 9 = Escape NoSymbol Escape
keycode 10 = 1 section 1 section
keycode 11 = 2 braceleft 2 braceleft
keycode 12 = 3 braceright 3 braceright
keycode 13 = 4 asciitilde 4 asciitilde
keycode 14 = 5 percent 5 percent
keycode 15 = 6 asciicircum 6 asciicircum
keycode 16 = 7 ampersand 7 ampersand
keycode 17 = 8 asterisk 8 asterisk
keycode 18 = 9 bracketleft 9 bracketleft
keycode 19 = 0 bracketright 0 bracketright
keycode 22 = BackSpace Delete BackSpace Delete
keycode 24 = q Q q Q
keycode 25 = w W w W
keycode 26 = e E e E
keycode 27 = r R r R
keycode 28 = t T t T
keycode 29 = y Y y Y
keycode 30 = u U u U
keycode 31 = i I i I
keycode 32 = o O o O
keycode 33 = p P p P
keycode 34 = parenleft NoSymbol parenleft
keycode 35 = parenright NoSymbol parenright
keycode 36 = Return Multi_key Return
keycode 37 = Control_L NoSymbol Control_L
keycode 38 = a A a A
keycode 39 = s S s S
keycode 40 = d D d D
keycode 41 = f F f F
keycode 42 = g G g G
keycode 43 = h H h H
keycode 44 = j J j J
keycode 45 = k K k K
keycode 46 = l L l L
keycode 47 = semicolon NoSymbol semicolon
keycode 48 = apostrophe NoSymbol apostrophe
keycode 49 = grave NoSymbol grave
keycode 50 = Shift_L NoSymbol Shift_L
keycode 52 = z Z z Z
keycode 53 = x X x X
keycode 54 = c C c C
keycode 55 = v V v V
keycode 56 = b B b B
keycode 57 = n N n N
keycode 58 = m M m M
keycode 59 = comma less comma less
keycode 60 = period greater period greater
keycode 61 = slash NoSymbol slash
keycode 62 = Shift_R NoSymbol Shift_R
keycode 64 = Alt_L NoSymbol Alt_L
keycode 65 = space NoSymbol space
keycode 66 = Caps_Lock NoSymbol Caps_Lock
keycode 67 = F1 NoSymbol F1
keycode 68 = F2 NoSymbol F2
keycode 69 = F3 NoSymbol F3
keycode 70 = F4 NoSymbol F4
keycode 71 = F5 NoSymbol F5
keycode 72 = F6 NoSymbol F6
keycode 73 = F7 NoSymbol F7
keycode 74 = F8 NoSymbol F8
keycode 75 = F9 NoSymbol F9
keycode 76 = F10 NoSymbol F10
keycode 82 = minus NoSymbol minus NoSymbol
keycode 83 = Home quotedbl Home quotedbl
keycode 86 = plus NoSymbol plus NoSymbol
keycode 87 = Prior Multi_key Prior Multi_key
keycode 88 = End XF86_Switch_VT_2 End XF86_Switch_VT_2
keycode 89 = Next XF86_Switch_VT_1 Next XF86_Switch_VT_1
keycode 95 = F11 NoSymbol F11
keycode 96 = F12 NoSymbol F12
keycode 118 = Insert NoSymbol Insert
keycode 132 = yen NoSymbol yen
keycode 187 = parenleft NoSymbol parenleft
keycode 188 = parenright NoSymbol parenright
keycode 191 = acute NoSymbol acute
keycode 192 = bar NoSymbol bar
keycode 193 = underscore NoSymbol underscore
keycode 194 = numbersign NoSymbol numbersign
keycode 195 = exclam NoSymbol exclam
keycode 196 = sterling NoSymbol sterling
keycode 197 = quotedbl NoSymbol quotedbl
keycode 198 = at NoSymbol at
keycode 199 = colon NoSymbol colon
keycode 200 = dollar NoSymbol dollar
keycode 201 = EuroSign NoSymbol EuroSign
keycode 222 = question NoSymbol question
keycode 235 = Tab NoSymbol Tab</pre>}}

Ok, now let's break this down a little. <code>keycode 38 = a A a A</code> - the first two letters after the = sign are what you'll get if you press the button marked A with and without holding "shift". The next two are with and without shift modifier together with a second modifier, but since there's no second modifier on the Pandora, this is redundant really. What about Fn, you may ask, isn't that a second modifier? The Fn-key acts on a lower level, and is not seen as a separate key. Instead, there are separate keycode entries for all Fn keys (the ones marked in blue on your Pandora). "NoSymbol" means that the combination doesn't produce a character. You can find a full list of symbols (or "keysyms") that you can use [http://wiki.linuxquestions.org/wiki/List_of_Keysyms_Recognised_by_Xmodmap over here].

You can edit the .pndXmodmap file itself if you want to. That'll change the default keyboard layout you have at startup.

But you can also make secondary custom keyboard layouts.

For example, here's how to make a selectable custom Russian keyboard layout:

====Making a custom Russian keyboard layout====
Make two new files inside <code>/media/yourSDcard/pandora/appdata/kblayout/keymaps</code>. One called "RU-translit" (the name doesn't matter), one called ".rumodmap" (the dot at the start of the name is to make it not show up in the Keyboard Layout Changer menu as a keymap; that's the function of the ''first'' file you made). Put this text in the RU-translit file:
./setxkbmap -layout us
xmodmap keymaps/.rumodmap

Put this text in the .rumodmap file:

{{HideableNotes|<pre>keycode 9 = Escape NoSymbol Escape
keycode 10 = 1 section 1 section
keycode 11 = 2 braceleft 2 braceleft
keycode 12 = 3 braceright 3 braceright
keycode 13 = 4 asciitilde 4 asciitilde
keycode 14 = 5 percent 5 percent
keycode 15 = 6 asciicircum 6 asciicircum
keycode 16 = 7 ampersand 7 ampersand
keycode 17 = 8 asterisk 8 asterisk
keycode 18 = 9 bracketleft 9 bracketleft
keycode 19 = 0 bracketright 0 bracketright
keycode 22 = BackSpace Delete BackSpace Delete
keycode 24 = Cyrillic_ya Cyrillic_YA Cyrillic_ya Cyrillic_YA
keycode 25 = Cyrillic_zhe Cyrillic_ZHE Cyrillic_zhe Cyrillic_ZHE
keycode 26 = Cyrillic_ie Cyrillic_IE Cyrillic_ie Cyrillic_IE
keycode 27 = Cyrillic_er Cyrillic_ER Cyrillic_er Cyrillic_ER
keycode 28 = Cyrillic_te Cyrillic_TE Cyrillic_te Cyrillic_TE
keycode 29 = Cyrillic_yeru Cyrillic_YERU Cyrillic_yeru Cyrillic_YERU
keycode 30 = Cyrillic_u Cyrillic_U Cyrillic_u Cyrillic_U
keycode 31 = Cyrillic_i Cyrillic_I Cyrillic_i Cyrillic_I
keycode 32 = Cyrillic_o Cyrillic_O Cyrillic_o Cyrillic_O
keycode 33 = Cyrillic_pe Cyrillic_PE Cyrillic_pe Cyrillic_PE
keycode 34 = parenleft NoSymbol parenleft
keycode 35 = parenright NoSymbol parenright
keycode 36 = Return Multi_key Return
keycode 37 = Control_L NoSymbol Control_L
keycode 38 = Cyrillic_a Cyrillic_A Cyrillic_a Cyrillic_A
keycode 39 = Cyrillic_es Cyrillic_ES Cyrillic_es Cyrillic_ES
keycode 40 = Cyrillic_de Cyrillic_DE Cyrillic_de Cyrillic_DE
keycode 41 = Cyrillic_ef Cyrillic_EF Cyrillic_ef Cyrillic_EF
keycode 42 = Cyrillic_ghe Cyrillic_GHE Cyrillic_ghe Cyrillic_GHE
keycode 43 = Cyrillic_che Cyrillic_CHE Cyrillic_che Cyrillic_CHE
keycode 44 = Cyrillic_shorti Cyrillic_SHORTI Cyrillic_shorti Cyrillic_SHORTI
keycode 45 = Cyrillic_ka Cyrillic_KA Cyrillic_ka Cyrillic_KA
keycode 46 = Cyrillic_el Cyrillic_EL Cyrillic_el Cyrillic_EL
keycode 47 = semicolon NoSymbol semicolon
keycode 48 = apostrophe NoSymbol apostrophe
keycode 49 = grave NoSymbol grave
keycode 50 = Shift_L NoSymbol Shift_L
keycode 52 = Cyrillic_ze Cyrillic_ZE Cyrillic_ze Cyrillic_ZE
keycode 53 = Cyrillic_ha Cyrillic_HA Cyrillic_ha Cyrillic_HA
keycode 54 = Cyrillic_tse Cyrillic_TSE Cyrillic_tse Cyrillic_TSE
keycode 55 = Cyrillic_ve Cyrillic_VE Cyrillic_ve Cyrillic_VE
keycode 56 = Cyrillic_be Cyrillic_BE Cyrillic_be Cyrillic_BE
keycode 57 = Cyrillic_en Cyrillic_EN Cyrillic_en Cyrillic_EN
keycode 58 = Cyrillic_em Cyrillic_EM Cyrillic_em Cyrillic_EM
keycode 59 = comma less comma less
keycode 60 = period greater period greater
keycode 61 = slash NoSymbol slash
keycode 62 = Shift_R NoSymbol Shift_R
keycode 64 = Alt_L NoSymbol Alt_L
keycode 65 = space NoSymbol space
keycode 66 = Caps_Lock NoSymbol Caps_Lock
keycode 67 = Cyrillic_yu Cyrillic_YU Cyrillic_yu Cyrillic_YU
keycode 68 = Cyrillic_e Cyrillic_E Cyrillic_e Cyrillic_E
keycode 69 = Cyrillic_softsign Cyrillic_SOFTSIGN Cyrillic_softsign Cyrillic_SOFTSIGN
keycode 70 = Cyrillic_sha Cyrillic_SHA Cyrillic_sha Cyrillic_SHA
keycode 71 = Cyrillic_shcha Cyrillic_SHCHA Cyrillic_shcha Cyrillic_SHCHA
keycode 72 = Cyrillic_io Cyrillic_IO Cyrillic_io Cyrillic_IO
keycode 73 = Cyrillic_hardsign Cyrillic_HARDSIGN Cyrillic_hardsign Cyrillic_HARDSIGN
keycode 74 = F8 NoSymbol F8
keycode 75 = F9 NoSymbol F9
keycode 76 = F10 NoSymbol F10
keycode 82 = minus Prior minus Prior
keycode 83 = Home quotedbl Home quotedbl
keycode 86 = plus NoSymbol plus NoSymbol
keycode 87 = Prior Multi_key Prior Multi_key
keycode 88 = End XF86_Switch_VT_2 End XF86_Switch_VT_2
keycode 89 = Next XF86_Switch_VT_1 Next XF86_Switch_VT_1
keycode 95 = F11 NoSymbol F11
keycode 96 = F12 NoSymbol F12
keycode 118 = Delete Insert Delete
keycode 132 = yen NoSymbol yen
keycode 187 = parenleft NoSymbol parenleft
keycode 188 = parenright NoSymbol parenright
keycode 191 = acute NoSymbol acute
keycode 192 = bar NoSymbol bar
keycode 193 = underscore NoSymbol underscore
keycode 194 = numbersign NoSymbol numbersign
keycode 195 = exclam NoSymbol exclam
keycode 196 = sterling NoSymbol sterling
keycode 197 = quotedbl NoSymbol quotedbl
keycode 198 = at NoSymbol at
keycode 199 = colon NoSymbol colon
keycode 200 = dollar NoSymbol dollar
keycode 201 = EuroSign NoSymbol EuroSign
keycode 222 = question NoSymbol question
keycode 235 = Tab NoSymbol Tab</pre>}}

Once that's done, you can open the Keyboard Layout Changer, choose "RU-translit", and your keyboard layout will change to a layout similar to [http://i.imgur.com/O96Pu.gif this one], with extra letters replacing F1-F7 (note: for those 7 letters, you can only use the Shift on the Pandora's front face, not the left shoulder button). To change back, open Keyboard Layout Changer again and select "default".

In the same way, you can create any other sorts of custom layouts. The easiest way to create a new modmap file is to copy+paste the contents of <code>/home/username/.pndXmodmap</code> into a new file in the <code>/media/yourSDcard/pandora/appdata/kblayout/keymaps</code> directory and make adjustments to whatever you want to change.

==How many keypresses can it detect at once?==
It can detect two "regular" keys being pressed at once[http://www.gp32x.com/board/index.php?s=&showtopic=44326&view=findpost&p=651104]. However, this restriction does not apply to the game controls, or the central "Menu" keys.

* The keyboard is listed on p.20 of the hackers manual

== Dpad ==
[[File:dpad.jpg|thumbnail|right|D-pad]]
8way D-pad designed by DaveC.
 
== ABXY ==
The abxy-cluster provides quick and easy access to ingame options. It is also used for hotkeys in [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PND-manager]]
[[File:abxy.jpg|thumbnail|right|ABXY]]

[[Category:Keyboard]]
[[Category:Software]]
[[Category:Tutorials]]
[[Category:Optimization]]

Boot setup

2013-12-18T23:34:46Z

Edlee: /* Setting up mutliple-partition SD cards for booting */

The uBoot bootloader normally boots the OS from NAND, but it can be inhibited by pressing R while starting up to for example pick SD-card booting. This can also be set up with text-files, making it the default behaviour.

==Set up your boot.txt==

Create a new file called boot.txt (or autoboot.txt if you want to boot automatically) and copy and paste the text below. Copy that file to the root of the root of the SD card.

{{warning
|If you edit the file on Windows, use an advanced text editor like [http://notepad-plus-plus.org/ Notepad++] and be sure to convert to UNIX format (in NP++: Edit -> EOL Conversion -> UNIX format). If you have DOS linebreaks, ext2load will fail with an error like "file not found" as it appends an hidden character to the uImage file name.
}}boot.txt (from the [http://openpandora.org/firmware/README.txt official firmware site])
<source lang="bash">
setenv bootargs root=/dev/mmcblk0p1 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ext2load mmc 0 0x80300000 /boot/uImage
bootm 0x80300000
</source>
Note: If you chose ext3 instead of ext2 for the partition containing the kernel, the second line still starts with ext2load. There is no ext3load.

Note: depending on firmware version kernels might be at several, sometimes multiple locations, so you have to choose one:
* /boot/uImage-3 - the default 3.2 kernel (recommended)
* /lib/boot/uImage - alternative location of 3.2 kernel on certain older firmwares
* /boot/uImage - mostly a symlink to the latest kernel on recent firmwares

Be aware though that this boot.txt assumes you have formatted your card with ext2 and loads the kernel off the SD card. It is technically possible to boot the kernel from NAND but still run the rest of the file system from your SD card with following boot.txt
<source lang="bash">
setenv bootargs root=/dev/mmcblk0p1 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ubi part boot && ubifsmount boot && ubifsload ${loadaddr} uImage && bootm ${loadaddr} && boot
</source>
However this is not recommended because kernel modules on SD card will likely be not compatible with kernel on NAND.

Both boot.txt's assume you are booting from the left SD card slot, first partition. You can change "mmcblk0p1" to "mmcblk1p1" if you want to boot from the right slot (but boot.txt must still be on a card on the left slot).

===Setting up multiple-partition SD cards for booting===

It is possible to have several partitions on the SD card and boot from one of them.
E.g. if you have three partitions on the card like this:
*Partition 1: FAT
*Partition 2: ext2 (where the rootfs should be placed)
*Partition 3: swap

How it's done:

1. Put uBoot's boot control files "boot.txt" and/or "autoboot.txt" into the root of the '''first partition''' of the card (FAT partition in this example)

2. Make "boot.txt" and "autoboot.txt" point U-Boot to the '''partition, which holds the root file system''' of your Linux system. This would be parition 2 in this example (ext2 FS).
This is done '''using the "root" parameter of setenv'''.

3. Make "boot.txt" and "autoboot.txt" point U-Boot to the correct '''location to boot your kernel from'''.
This kernel location can be any FAT or ext2/3/4 partition on the SD card.
The uBoot commands '''"fatload" and "ext2load" with their parameter "mmc x:y"''' are repsonsible for loading the kernel. Choose the command, which addresses the file system the kernel is located on and make sure to correctly adapt the values x and y.

This common example boots the kernel from the FAT partition (then this is a "boot partition"), and uses the ext2 file system as root FS:

<source lang="bash">
setenv bootargs root=/dev/mmcblk0p2 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
fatload mmc 0:1 0x80300000 uimage
bootm 0x80300000
</source>

If you put the kernel into the root file system's /boot directory, the second line would be different:

<source lang="bash">
setenv bootargs root=/dev/mmcblk0p2 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ext2load mmc 0:2 0x80300000 /boot/uImage
bootm 0x80300000
</source>

'''Note: '''

For both the "root=" kernel argument and the "mmc x:y" argument of the fatload/ext2load commands, slot numbering begins at 0 (0 is left SD slot, 1 is right SD slot) and partition numbering begins at 1!

'''Recommendation:'''

Put the kernel into another partition than the root FS is located.
Reason: In case the root FS partition is flagged "inconsistent" after a system crash or sudden SD card removal, uBoot won't be able to boot from that partition anymore. But the file system cleanup routines can only be run, once the kernel has been booted. Hence it's safer to put the kernel on a different partition.

==Boot the system==

As you power up the Pandora, hold the shoulder button R. A menu should appear, allowing you to boot from the SD card. (this step isn't necessary if you chose to create an autoboot.txt instead of boot.txt). Remember that this will be an un-configured image, taking a little while longer to boot, and giving the first-run dialogue.

==Access the NAND==
Once you're booted into the system from SD, you may want access to the NAND rootfs. The following will let you do that.
<source lang="bash">
sudo mkdir /mnt/nand
sudo ubiattach /dev/ubi_ctrl -m 4
sudo mount -t ubifs ubi0:rootfs /mnt/nand
</source>

==Other information==
An alternative approach to using an SD card to increase the space accessible to the system is [[Extend_Utils#OS_Extends | OS Extend]]. This allows the root filesystem to exist on more than one physical device.

==References==
*[http://openpandora.org/firmware/ Official firmware page]
*[http://repo.openpandora.org/?page=detail&app=sd-install-2011-03-10 The GUI-driven SD installer by David Boucher]

=Copy the files to your SD card=
Navigate (cd) to the directory with the .tar.bz2 file you just downloaded (or made) and do:

<source lang="bash">
sudo tar -xvjf <tarfile>.tar.bz2 -C <SD card>
</source>

If you're doing this on your Pandora, <SD card> is something like /media/mmcblk0p1 (first SD card slot on Pandora). On Ubuntu it would be something like /media/disk if it has no label. You can also try using GUI tools for this, but I didn't have very good luck with them.

===OR copy your firmware from the NAND to the SD card===

The following will ask for your password. All the operations need root permissions so I thought it would be wasteful to sprinkle sudo to everything.
We will bind mount the root fs to an alternative location ("/mp"), under which other filesystems mounted under root (like the kernel virtual filesystems /proc and /sys, and your SD card.) wont be visible. This allows us to take a live copy of the NAND contents to the SD filesystem.

<source lang="bash">
sudo su
mkdir /mp
mount --bind / /mp
cp -va /mp/* /media/<SD card>
umount /mp
rmdir /mp
exit
</source>

== serial port ==
In an unlikely event that you can get serial output from EXT port, be aware that serial device has changed several times (due to the driver and port configuration changes in the kernel):
* openpandora.org 2.6.27: ttyS0
* mainline upto 2.6.36: ttyS2
* mainline/openpandora.org 2.6.37 and up: ttyO2
This is relevant for console= bootarg.

[[Category:Documentation]]
[[Category:Tutorials]]
[[Category:Booting]]
[[Category:Storage card]]
[[Category:Operating system]]

Introduction to PNDs

2013-12-15T09:16:18Z

Edlee: /* How Do I Make .PNDs? */

{{IntroNote|For developers: [[Libpnd hub]]}}

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

== How do I run a PND-application? ==

Put your pnd-files on your SD card and insert the SD card into either slot of your Pandora.

Using the file browser, you can double-click on the pnd-file to run it. However, more normally pnd files are put in special folders so they get picked up by the Pandora's OS and are made easier to find and run.

== Where do .PNDs Go? ==
[[Image:PandoraSD.png|thumb|alt=SD card folder structure|This is what the folder structure on your SD card should look like. The drive letter and card name will vary; they're not important.]]
Put .pnd-files into specific directories if you want them to show up in the Start menu or on your Pandora desktop, or in Minimenu.

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

{|class="wikitable"
!Folder!!Note
|-
|/pandora/desktop||pnd files show up on the desktop background
|-
|/pandora/menu||show up in the Applications menu or in minimenu(under the categories suggested by the developer)
|-
|/pandora/apps||show up in all places; the desktop, the apps menu and in Minimenu
|-
|/pandora/mmenu||show up only in minimenu, ignored by other GUIs
|}

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 DON'T .PND files 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 you'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.

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

example: 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.

=== Using a start-up script ===
In an ideal world, your application will be completely self-contained and can be run directly without any kind of set-up. It is however often necessary to tweak settings or request input from the user before starting your application. This is easily achieved by having the [[PND]] specify a shell script as its executable, which then in turn runs the application. The general structure of such a script is:
<source lang="bash">
#!/bin/sh

# Do stuff here...

./my_app

# Clean-up
</source>
The first line identifies the file as a shell script, run using "/bin/sh" as the shell. The other lines beginning with a "#" are comments. Before the application is started, parameters can be gathered and/or set. The application itself then gets run by the "./my_app" line, which means "execute the file ''my_app'' in the current directory". When the application exits, it may be necessary to restore previous settings, delete temporary files, or perform some other kinds of cleaning up.

=== Avoiding NAND writes by setting $HOME ===
Many applications write configuration data to the user's home directory by default. This is not desirable on the Pandora as this directory resides on the [[NAND]] filesystem. It is however often possible to fool an application into writing to a different directory by setting the $HOME environment variable.
<source lang="bash">
export HOME=`pwd`
export HOME=$(pwd)
</source>

=== Providing a default configuration ===
If your application uses a configuration file, you'll usually want to include this in the PND. However, if you simply leave this file in the root of the PND, it will effectively be read-only, preventing the application or user from writing to it. A simple solution is to provide a default configuration file with a different name, and copy this the first time the application is run. The file will then be created under ''appdata'', and can therefore easily be edited.
<source lang="bash">
# Method 1: check if file exists, otherwise copy default.
if [ ! -f app.conf ] ; then
cp default.conf app.conf
fi

# Method 2: Same as above, less typing.
[ -f app.conf ] || cp default.conf app.conf

# Method 3: using a non-destructive copy.
cp --no-clobber default.conf app.conf
</source>

==== Nub Configuration ====
This is a little (but not much!) lengthier - see the page on [[PND nub modes]].

=== Making writable directories ===
If your application requires that directories be writable for the application, don't put them in the PND, but create them at run-time:
<source lang="bash">
# Bad! This will cause an error after the first run, as the directory will already exist.
mkdir saved_data

# Better to use "-p" which won't complain about existing directories.
mkdir -p saved_data

# Added bonus: this allows you to create whole trees in one go.
mkdir -p saved_data/foo saved_data/bar/with/deep/sub/dirs
</source>

=== Loading shared libraries ===
If your application requires shared libraries which aren't part of the standard firmware, they can be included in the PND along with the executable. In order for the system to be able to find the libraries, it must be told which directories to search. This can be done by setting the LD_LIBRARY_PATH environment variable. For example:
<source lang="bash">
export LD_LIBRARY_PATH=`pwd` # Load libraries in the root directory of the PND.
export LD_LIBRARY_PATH=`pwd`/libs # Load libraries in the "libs" subdirectory of the PND.
</source>

=== Getting a file/directory from the user ===
Its often necessary to ask the user for the location of a file or directory. This may be because your application requires files which aren't included in the PND itself, or simply because you application doesn't have a built in file picker. The commands below will prompt the user for a file, then run "my_app" with that file as an argument. Note the use of different sorts of quotes which is important for proper operation and handling spaces in file names.
<source lang="bash">
FILE="`zenity --file-selection --title='Select a File'`"
./my_app "$FILE"
</source>

=== Saving a file/directory name ===
If your application always asks for a file at start-up, it's handy to remember the location for next time. This can be done by writing the name of the directory to a file in appdata, and reading it back next time the application is run.
<source lang="bash">
SAVEDIR=./dir.saved # Name of the file we'll save the directory name to

# Did we save a directory last time? If so, read it into a variable.
DIR=`cat $SAVEDIR 2> /dev/null`

# Remember where we are right now, as we'll need to come back later.
PNDDIR=`pwd`

# Does the directory still exist?
if [ -d "$DIR" ] ; then
# Yes, go to that directory before Zenity is started.
cd "$DIR"
else
# No, try to go to /media (where the SD cards are mounted)
# or if that fails, go to "/" as a last resort.
cd /media 2> /dev/null || cd /
fi

# Get a file name form the user. Our current directory is now that which
# was saved, so that's where Zenity will start.
FILE=`zenity --file-selection --title="Select a file"`

# If the file selector failed, or the user hit cancel, exit now.
[ $? -eq 0 ] || exit 1;

# Go back to the PND's mount point.
cd $PNDDIR

# Save the file's directory for next time.
dirname "$FILE" > $SAVEDIR

# Run our app with the file as an argument.
./my_app "$FILE"
</source>

=== Checking a file's contents ===
Maybe your application requires some file which cannot be distributed with the PND, either for legal reasons or due to size limitations. A prime example of this is BIOS files used for emulators. Simply copying the file to the current directory will be enough to save it to your program's appdata, but it can also be useful to check the contents of the file are indeed what your application expects.

One way of doing this is to check the file's contents using a hash. A hash is a mathematical formula which can be used to create a "fingerprint" of a file. Two identical files will always generate the same hash value, so knowing this one value is enough to check if two files match. The MD5 hash is a popular choice, and can be easily generated for a given file like so:
<source lang="bash">
$ md5sum bios.img
cfcfd01f1b0dfa97f07cb286b2942dc2 bios.img
</source>

Save this output to a text file named ''bios.md5'' and put it in your PND root directory. The following commands can then be used in your start-up script to copy a file specified by the user, and check it's hash.

<source lang=bash>
BIOS=bios.img # The name of our BIOS file

# Check if the BIOS file already exists.
if [ ! -f ./$BIOS ] ; then
# Not found, so get a file name from the user.
cp "`zenity --file-selection --title="Select your $BIOS file"`" $BIOS
if [ $? != 0 ] ; then
# User hit cancel, bail out.
zenity --error --text="Sorry, emulator cannot run without a BIOS file."
exit 1
fi

# Check the MD5 hash of the given file against our known-good value.
# If the match fails, ask the user if they'd like to try it anyway.
md5sum -c bios.md5 || zenity --question \
--text="BIOS does not appear to be the correct version. Use it anyway?"

if [ $? != 0 ] ; then
# File did not match hash, and the user opted not to try it anyway,
# so remove the copied file and bail out.
rm -f $BIOS
exit 1
fi
fi

# Run our emulator with the BIOS file as an argument.
./my_emu "$BIOS"
</source>

= Advanced topics =

== I want to override the .PND icon, name, or other settings, how is this done? ==

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 .png 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 anything 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.
* The category list uses the existing desktop standard. See [http://standards.freedesktop.org/menu-spec/latest/apa.html here] for a list of categories and subcategories supported.
* 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.

== How Do I Make .PNDs? ==

{{IntroNote | The following is a work in progress, the instructions in here may or may not work for you. It was taken from PND quickstart.}}

The steps to produce a pnd file are as follows:

* create a directory to represent the application on SD card; i.e.: ./mame-app

* create a PXML.xml file and drop it into the dir (./mame-app/PXML.xml); genpxml script can be used, or do it by hand

* drop the executable and data files into this dir (say, ./mame-app/mame.bin, and ./mame-app/artwork/foo, etc.) <- note, with a PXML.xml and executable, your Pandora can now find and run your app without even bundling it into a .pnd!

* invoke /usr/pandora/scripts/pnd_make.sh (or on Windows, various commands in the command-line) to produce mame4all-pandora-1.0-arm.pnd or whatever you want to call it (foobearspanky.pnd, we don't care.)

* you're done, distribute it as you see fit

=== (alternate instructions) ===

For these instructions, you will first need to grab the example file, [http://www.shiranui.in/pndexample.tar.gz here].

* Edit ./pnds.sh. I use that script to handle multiple apps at once. Each line represents a command line for an app / game to turn the directory into a PND. If I change the app / game, I simply uncomment the line in pnds.sh so that I can easily create or update multiple PNDs by simply running one single script.
* Run ./pnds.sh
* Upload

Don't forget to check the license conditions for anything you re-distribute.

== PXML.xml file? ==

The PXML.xml file is the pnd file's metadata file and specifies things like:
* A description of the software
* A link to the icon filename
* What version it is
* The author, and their website
* Whether it's a beta or release version
* The menu categories the pnd file should appear in
* The license the code is distributed under
* Preview pictures, for display in minimenu or on the [[http://repo.openpandora.org/ repo]]

You can use genpxml.sh to generate a template PXML.xml file for you (in /usr/pandora/scripts/), but
perhaps simplest way to make your first PXML.xml file is to look at an example one from a real pnd file, from the repo (where PXML.xml file are guaranteed to be valid). The PXML.xml file will be inside the pnd file's root folder, and you can look at it using a text editor.

== How Do I Look Inside a .PND? ==

To open a PND, the easiest way is probably to use the [http://boards.openpandora.org/index.php?/topic/3756-pndtools/ PNDTools] or [http://boards.openpandora.org/index.php?/topic/3805-pnd-manager/ PNDManager] programs, which can browse and create PNDs. They're Windows-only, currently.

You could also install 7zip on your home PC, change the .pnd's file extension to .sfs, and 7zip should be able to open it. (This is a simple way to look into a .pnd on Ubuntu: <code>unsquashfs FILE.pnd</code> needs squashfs-tools installed) [http://boards.openpandora.org/index.php?/topic/3594-pnd-criticism/page__view__findpost__p__62546] On the Pandora, you can run a PND and look at what's inside [[Basic Linux Guide|/mnt/tmp]]. To do this in a terminal (on PC or Pandora), see [http://www.gp32x.com/board/index.php?/topic/58937-how-to-mount-a-pnd-and-see-the-gooey-bits-inside/ this tutorial].

The [[PND Cookbook]] contains recipes for common PND tasks, like setting up your application's environment and configuration, locating and copying files, etc.

== All these commands are hard. Give me a GUI tool to do it ==

Okay:

*'''PNDbuilder''' by freedomdown. [http://www.gp32x.com/board/index.php?/topic/58587-pndbuilder/ Discussion]. [http://www.freedomdown.ca/storage/pndb.pnd Download v1.1 for Pandora].

== How do I make .PNDs on Windows? ==

=== Command-line ===

For this command-line tutorial, I will assume you have already created a PXML.xml file.

==== Preparations ====
Get yourself mkisofs tools; for example, grab from here: http://www.student.tugraz.at/thomas.plank/ -- get cdrtools-2.01-win32-bin.zip and DLL version 1.5.25, and extract to somewhere. That lets you run 'mkisofs' to spit out .iso files

''If you want to make a compressed image, use squashfs tools here: ftp://ftp.slax.org/useful-binaries/win32/squashfs-tools/''

==== Generate the actual PND-file ====

Make yourself the iso; this step produces the iso, but to turn the iso into a pnd you need a couple last steps. You could also use some fancy iso-building tool.
<pre>mkisofs -o foo.iso -R /path/to/folder/myapp</pre>

Append PXML.xml to the .iso (yes, the PXML.xml is included in the iso, but we also want to append it for performance reasons.)
<pre>copy foo.iso+PXML.xml foo.step2</pre>

Append the icon PNG file to the .iso (if you have an icon; if not, you can leave this step out.)
<pre>copy foo.step2+myicon.png foo.pnd</pre>

Clean up:
<pre>del foo.step2 foo.iso</pre>

Profit!

=== GUI ===

You have a few choices here:
*'''PNDTools''' by foxblock. Discussion: [http://boards.openpandora.org/index.php?/topic/3756-pndtools/ OP], [http://www.gp32x.com/board/index.php?/topic/60060-pndtools/ GP32X]. Can browse and create PNDs. Two (simple and advanced) editors for PXML creation.
*'''PNDBuilder''' by StreaK. [http://www.gp32x.com/board/index.php?/topic/59862-openpandora-pnd-builder-for-windows-linux/ Discussion] [http://www.gp32x.com/board/index.php?/topic/47088-pnd-builder-for-windows/ (old)]. Can create PNDs and edit PXML files.
*'''PNDManager''' by Speaker Ender. [http://boards.openpandora.org/index.php?/topic/3805-pnd-manager/ Discussion].
*'''PNDbuilder''' by freedomdown. [http://www.gp32x.com/board/index.php?/topic/58587-pndbuilder/ Discussion].

== Mac OSX ==

TBD

This is a list of '''frequently asked questions''' about using the Pandora PND package format. For factual and other kinds of questions, use the [[Special:Search|search box]]. If your question is not answered on this page, do some research and include it!

==The PND system==

===What is a PND file?===
:A PND file is a compact file that contains one or more runnable applications for the Pandora. The file is basically an archive (like a ZIP, RAR or ISO) that contains all the data that the provided set of applications require, along with some meta data about the applications themselves.

===Why are PNDs useful?===
:Normally, on an ordinary computer, it is necessary to install an application in order to run it. This usually happens in one of many different ways; an installer might be run, or an archive might become extracted, etc.
:PND files are used to allow for applications to be executed ''without'' them being installed first. They are supposed to work in a way similar to game cartridges, in that they contain all of the necessary information in one tight package that can be executed independently.
:This system is inspired by similar systems such as the Apple OS 10 DMG file system, the Puppy Linux package format, or the Haiku Box package management system.

===Can I modify a PND file?===
:You can, but you need easily obtained open source freeware special tools to do so. (These tools are included by most Linux distributions by default, but are downloads for Windows and Mac OSX users.) It is advised that only developers modify or create PND files.

===Can a PND file modify itself?===
:No, not generally. A pnd-file, even after extended use may be copied anywhere and still be in its original state. Any changes the application has made will have been redirected to its appdata directory instead, so you have your self-contained directory of its changes.

===How does a PND store application data?===
:Since the PND cannot modify itself, there has to be a way for it to store runtime data, such as configuration files and user-added level files. This is achieved in the PND system by creating an application data directory for each application that is inside a PND. Since a PND can contain many applications, there can, and will, be multiple application data folders per PND, and each application declares its own application data folder name.
:The application data folders are located in "pandora/appdata/*" on the device that the PND is stored on.

===What desktop environments do pnd files work with?===
:As described below, the pnd-files will cause the system to spit out standard ".desktop" files for each application contained. The Pandora firmware includes several desktop environments (ie: menus) that understand those files (or operate with pnd-files directly.) The ".desktop" files are a standard however, so you are free to install other desktop environments and they should work fine out of the box with pnd-files, without any alteration whatsoever,

===Can a PND-file be unpacked and used?===
:A pnd-file may be unpacked into what is called a "PXML-application directory" if the packager of the pnd-file followed the specification. (ie: the icon and PXML.xml metadata are included in the contained filesystem and not just found at the end of the pnd-file.) An application directory may be auto-discovered and executed just like a pnd-file, but you can muck with the files in-place without a problem. When the application writes back to itself however, the changes will still be directed to the appdata directory as with a regular pnd-file.
:This is an advanced topic, noted here for completeness.

===Can the PND-file system be added to other Linux distributions?===
:It is very easy to add the PND system to other Linux distributions, be they Pandora oriented or not. As of 2010 the Pandora APIs are are a little Pandora-specific, but effort will be made to split off the PND-file support and Pandora-specific support into separate systems, so that non-Pandora Linux distributions can even more easily adopt the PND-file system should they wish to. Certainly however, if you're building a new distribution to run on the Pandora, it is absolutely trivial to include PND-file support (and other Pandora originated technologies), so please do, to help for a consistent user experience.

==Usage==

===How do I use PND files?===
:Using PND files on your Pandora is easy: You simply get hold of a PND file, presumably via a web page of some kind, and store it in a special folder on one of your SD cards. See the folder listing below. By default, both SD slots (and other mountable media) on the Pandora will be monitored for PND-files, though everything is configurable for advanced users.
:Once you've put your PND in a known location, the PND system will pick up the new PND, "activate" it, and create shortcut icons to the applications inside of the PND. You can then use these icons to launch the applications.

===How do I launch a PND application without putting it in a special location?===
:If you open a PND file in your file manager, the first application in the PND will be launched without you having to move the PND file.

This guide describes how to mount a PND file, so you can browse the files within (to find documentation, or otherwise eat its brain and gain its knowledge.)

''For now, the information is being compiled in [[http://www.gp32x.com/board/index.php?/topic/58937-how-to-mount-a-pnd-and-see-the-gooey-bits-inside this thread]] where I am fine tuning it with some expert help. When all the facts are straight, I will replicate the information here. -Gruso''

===How do I choose where the shortcut icons for a PND appear?===
:With the default configuration, there are four different folders you can put your PND files in to have their applications show up in different locations:
:* "/media/*/pandora/menu" - These PND-files will only generate shortcut icons in the system's application menu. ("*.desktop" files will be written to "/usr/share/applications")
:* "/media/*/pandora/desktop" - These PND files will only generate shortcut icons on the Desktop. ("*.desktop" files will be written to "~/Desktop")
:* "/media/*/pandora/apps" - Deprecated to some extent, this directory is used to be _both_ menu and desktop, without having to copy the pnd-file into /menu and /desktop (avoiding duplication)
:* "/usr/pandora/apps" This also extracts shortcut icons to the desktop. This path should not be touched, and is included to make an easy avenue for the Pandora firmware developers to include essential tools for the user, when bundled as pnd-files. (As of this writing early 2010, such tools are built into the firmware without being pnd-files, but the option exists still.)

==Advanced Information==

===How is a PND file structured?===
:The PND file is simply an archive or file system image (currently, ISO and SquashFS are supported) with a "PXML.xml" appended at the end. There can also be an accompanying icon that is appended as well.

===How does the PND discovery mechanism work?===
:There is an open source API for working with pnd-files and PXML-application directories (among other tasks); this API can be used by developers wishing to take advantage of the pnd auto-discovery system, such as when developing a new menu system say.
:There is a special process called "pndnotifyd" that uses this API to watch the PND search paths for file changes. Once it finds a new PND file, it uses the PXML.xml file to generate one or more "*.desktop" files for the PND. (A .desktop file is a open standard way of describing an application and how to execute it, and is supported across most popular desktop environments.)

===How do I change the search paths for PND files?===
:Simply edit the "/etc/pandora/conf/apps" file, and change the "searchpath" entry to include the paths you want to use. Paths are separated by colons (":") and may include wildcards (in the shape of "*") anywhere in the path.

===How do I configure different locations for my PND shortcuts?===
:Edit the file "/etc/pandora/conf/desktop" (The "desktop" refers to "*.desktop files"). It will look like this:
<pre>
# Open Pandora
# Desktop configuration

[desktop]
searchpath /media/*/pandora/desktop:/media/*/pandora/apps:/usr/pandora/apps
dotdesktoppath ~/Desktop/
iconpath /tmp

[menu]
searchpath /media/*/pandora/menu
dotdesktoppath /usr/share/applications
iconpath /tmp
</pre>
:You should leave the "iconpath" variables be, but you can change which paths are searched through and where "*.desktop" files are extracted with the "searchpath" and "dotdesktoppath" variables, respectively.

===How can I open a PND file to see what's inside?===
The simplest way is probably to use [http://boards.openpandora.org/index.php?/topic/3756-pndtools/ PNDTools] or [http://boards.openpandora.org/index.php?/topic/3805-pnd-manager/ PNDManager], which currently only work in Windows. You can also use them to edit PNDs and create them.

===How do I set up a script to run before/after a specific PND runs?===
(Using [http://sebt3.openpandora.org/pnd/pnd_run_installer.pnd pnd_run.sh] or as of Zaxxon HF6 Alpha 1) 
The pandora will look in the program's appdata folder for a bash script named PND_pre_script.sh to run before the PND is run, and PND_post_script.sh to run on the PND's closing. 
All information pulled from [http://www.pandorawiki.org/PND_nub_modes] and may be subject to change due to updates.

[[Category:PND]]
[[Category:FAQ]]