Pandora Wiki - User contributions [en]

PCSX-ReARMed

2023-01-12T08:08:23Z

Porg: /* Operational Controls during Gameplay */

{{warning|The information here is for version '''r8.''' Things may change in later versions as the emulator is updated.}}

{{Infobox Emulator|title=PCSX-ReARMed
|image=[[Image:Playstation-console.png|center|Playstation console]]
|download=[http://notaz.gp2x.de/releases/pcsxr/pcsx_rearmed_r18.pnd version r18]
|developer=Notaz
|license=[https://github.com/notaz/pcsx_rearmed/blob/master/COPYING GPLv2]
|porter=Notaz
|webpage=http://notaz.gp2x.de/pcsx_rearmed.php
|version=R18 (28-10-2013)
|status=Public Beta
|compatibility=[https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List (Google docs)]
}}
PCSX-ReARMed is a PlayStation 1 Emulator. A better alternative to [[PSX4Pandora]].

==Emulator Information==
===Development Status ===
In development with a beta version available.

===Compatibility===
A compatibility list is maintained as Google spreadsheet doc: [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 PSX compatibility list]

=== Related Links ===
*[http://www.gp32x.com/board/index.php?/topic/57973-pcsx-rearmed/ Development Thread & Discussion (GP32X)]
*[http://notaz.gp2x.de/cgi-bin/gitweb.cgi?p=pcsx_rearmed.git Source code (GIT)]

==Installation Instructions==
===Installation===
Download the latest version of the emulator from the repo ([http://repo.openpandora.org/?page=detail&app=package.pcsx_rearmed.notaz.r8 here]) and place it in one of the folders on your SD card according to the [[Introduction_to_PNDs#Where_do_.PNDs_Go.3F |PND guide]] (This guide will assume that you put the PND in /pandora/menu). In XFCE, the icon to the emulator should appear in the menu under 'menu -> Emulators -> PCSX-ReARMed' (if you put the PND in /pandora/menu), or on the desktop (if you put the PND in /pandora/desktop or /pandora/apps).

===ROM Images===
ROM files (Disc images) come in a range of formats, most commonly .iso, .img, .bin/.cue or .mdf/.mds. This emulator cannot handle compressed ROM files.
 
While it does not matter where the ROM files are placed, it is often easiest to put them somewhere that makes sense in relation to the PND for easy browsing. A good place to put them would be either in a clearly-named folder in the root of the SD card (e.g. /PS1) or in the same folder as the emulator PND (e.g. /pandora/menu/PS1). It does not matter how many ROM files are in the folder, or what directory structure is used.

Some images come as a .ecm file. These will not work in this emuator, but can be 'un-ECMed' by using the utility software [http://www.neillcorlett.com/ecm/ unecm], available at the linked website both as source code and as executable program files (=precompiled binaries, both 32 and 64 bit) for Windows, DOS, Mac OS X; on various Unix systems available through package managers as the package named "ecm"; and meanwhile also as a [http://notaz.gp2x.de/misc/pnd/unecm PND application by notaz].

=== BIOS ===
PCSX-ReARMed supports loading BIOSes. A minimum of one BIOS should be copied to [sd card]/pandora/appdata/pcsx_rearmed/bios/ ..and then selected in options->bios/plugins menu.
Loading a BIOS can potentially fix tons of bugs. It is highly recommended to activate it. A BIOS file is not strictly necessary, but not all games will work correctly without one.

==Usage==
[[Overclocking]] is often necessary to achieve acceptable emulation. See the [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List] for each game's tested speed.

===Nub Control===
Nub control is disabled by default (left joystick is mapped to the D-Pad). To enable it, select 'Controls->Nubs as Buttons' in the menu.

===Loading a Game===
Upon staring the emulator, you will be presented with a GUI. Select (with B) 'Load CD Image', then navigate to the folder where you keep your image files. If you cannot find them, try selecting '/..' until the directory at the top of the list (in white) shows '/', then select '/media' then '/SD_CARD' where SD_CARD is the name of your card, then navigate to the folder where you placed the files. '''NOTE: Only select files highlightes as either blue or white. Grey files will not work.'''
 
At any time during gameplay, you can press the spacebar to return to the menu, pausing the game session. You can select 'Resume Game' to continue playing.

===Default Controls===
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 35%;"
|- style="background: #ececec"
! PS1 Controller Button
! Pandora Button
|-
|Triangle (Green)
|Y (Gamepad)
|-
|Circle (Red)
|B (Gamepad)
|-
|Square (Pink)
|A (Gamepad)
|-
|X (Blue)
|X (Gamepad)
|-
|Start
|Start
|-
|Select
|Select
|-
|R
|Right Shoulder
|-
|L
|Left Shoulder
|-
|D-Pad (Up, Down, Left, Right)
|D-Pad (Up, Down, Left, Right)
|-
|Left Analog Stick (Up, Down, Left, Right)
|Left Nub (Up, Down, Left, Right)
|-
|Right Analog Stick (Up, Down, Left, Right)
|Right nub (Up, Down, Left, Right)
|}

===Operational Controls during Gameplay===
as of r23 (2022-03-14)
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: left; width: 35%;"
|- style="background: #ececec"
! Pandora Button
! Function
|-
| SPACE
| Pause emulation and open menu
|-
| 1
| Save to current slot
|-
| 2
| Load from current slot
|-
| 3
| Prev Slot (for next save/load operation)
|-
| 4
| Next slot (for next save/load operation)
|-
| 5
| Toggle Frameskip (Auto, Off, 1)
|-
| 6
| Take Screenshot
|-
| 7
| Toggle stats (None, FPS, FPS + CPU)
|-
| 8
| Toggle Scaler (default, double resolution, scale2x, eagle2x)
|-
| ⌫
| Toggle Fast Forward (off, on)
|}

== Creating images of Games ==
A short how-to for doing this on Linux is available: [[Creating images of PSX games using Linux]]. On Windows you can probably rely on the common tools for creating disc images, like for example Alcohol or the likes. There were some reports in the forums that using Nero for creating images does not work.

[[Category:Emulators]]

PCSX-ReARMed

2023-01-11T21:26:28Z

Porg: /* Usage */ Operational Controls during Gameplay

{{warning|The information here is for version '''r8.''' Things may change in later versions as the emulator is updated.}}

{{Infobox Emulator|title=PCSX-ReARMed
|image=[[Image:Playstation-console.png|center|Playstation console]]
|download=[http://notaz.gp2x.de/releases/pcsxr/pcsx_rearmed_r18.pnd version r18]
|developer=Notaz
|license=[https://github.com/notaz/pcsx_rearmed/blob/master/COPYING GPLv2]
|porter=Notaz
|webpage=http://notaz.gp2x.de/pcsx_rearmed.php
|version=R18 (28-10-2013)
|status=Public Beta
|compatibility=[https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List (Google docs)]
}}
PCSX-ReARMed is a PlayStation 1 Emulator. A better alternative to [[PSX4Pandora]].

==Emulator Information==
===Development Status ===
In development with a beta version available.

===Compatibility===
A compatibility list is maintained as Google spreadsheet doc: [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 PSX compatibility list]

=== Related Links ===
*[http://www.gp32x.com/board/index.php?/topic/57973-pcsx-rearmed/ Development Thread & Discussion (GP32X)]
*[http://notaz.gp2x.de/cgi-bin/gitweb.cgi?p=pcsx_rearmed.git Source code (GIT)]

==Installation Instructions==
===Installation===
Download the latest version of the emulator from the repo ([http://repo.openpandora.org/?page=detail&app=package.pcsx_rearmed.notaz.r8 here]) and place it in one of the folders on your SD card according to the [[Introduction_to_PNDs#Where_do_.PNDs_Go.3F |PND guide]] (This guide will assume that you put the PND in /pandora/menu). In XFCE, the icon to the emulator should appear in the menu under 'menu -> Emulators -> PCSX-ReARMed' (if you put the PND in /pandora/menu), or on the desktop (if you put the PND in /pandora/desktop or /pandora/apps).

===ROM Images===
ROM files (Disc images) come in a range of formats, most commonly .iso, .img, .bin/.cue or .mdf/.mds. This emulator cannot handle compressed ROM files.
 
While it does not matter where the ROM files are placed, it is often easiest to put them somewhere that makes sense in relation to the PND for easy browsing. A good place to put them would be either in a clearly-named folder in the root of the SD card (e.g. /PS1) or in the same folder as the emulator PND (e.g. /pandora/menu/PS1). It does not matter how many ROM files are in the folder, or what directory structure is used.

Some images come as a .ecm file. These will not work in this emuator, but can be 'un-ECMed' by using the utility software [http://www.neillcorlett.com/ecm/ unecm], available at the linked website both as source code and as executable program files (=precompiled binaries, both 32 and 64 bit) for Windows, DOS, Mac OS X; on various Unix systems available through package managers as the package named "ecm"; and meanwhile also as a [http://notaz.gp2x.de/misc/pnd/unecm PND application by notaz].

=== BIOS ===
PCSX-ReARMed supports loading BIOSes. A minimum of one BIOS should be copied to [sd card]/pandora/appdata/pcsx_rearmed/bios/ ..and then selected in options->bios/plugins menu.
Loading a BIOS can potentially fix tons of bugs. It is highly recommended to activate it. A BIOS file is not strictly necessary, but not all games will work correctly without one.

==Usage==
[[Overclocking]] is often necessary to achieve acceptable emulation. See the [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List] for each game's tested speed.

===Nub Control===
Nub control is disabled by default (left joystick is mapped to the D-Pad). To enable it, select 'Controls->Nubs as Buttons' in the menu.

===Loading a Game===
Upon staring the emulator, you will be presented with a GUI. Select (with B) 'Load CD Image', then navigate to the folder where you keep your image files. If you cannot find them, try selecting '/..' until the directory at the top of the list (in white) shows '/', then select '/media' then '/SD_CARD' where SD_CARD is the name of your card, then navigate to the folder where you placed the files. '''NOTE: Only select files highlightes as either blue or white. Grey files will not work.'''
 
At any time during gameplay, you can press the spacebar to return to the menu, pausing the game session. You can select 'Resume Game' to continue playing.

===Default Controls===
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 35%;"
|- style="background: #ececec"
! PS1 Controller Button
! Pandora Button
|-
|Triangle (Green)
|Y (Gamepad)
|-
|Circle (Red)
|B (Gamepad)
|-
|Square (Pink)
|A (Gamepad)
|-
|X (Blue)
|X (Gamepad)
|-
|Start
|Start
|-
|Select
|Select
|-
|R
|Right Shoulder
|-
|L
|Left Shoulder
|-
|D-Pad (Up, Down, Left, Right)
|D-Pad (Up, Down, Left, Right)
|-
|Left Analog Stick (Up, Down, Left, Right)
|Left Nub (Up, Down, Left, Right)
|-
|Right Analog Stick (Up, Down, Left, Right)
|Right nub (Up, Down, Left, Right)
|}

===Operational Controls during Gameplay===
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: left; width: 35%;"
|- style="background: #ececec"
! Pandora Button
! Function
|-
| SPACE
| Pause emulation and open menu
|-
| 1
| Save to current slot
|-
| 2
| Load from current slot
|-
| 3
| Prev Slot (for next save/load operation)
|-
| 4
| Next slot (for next save/load operation)
|-
| 5
| Toggle Frameskip (Auto, Off, 1)
|-
| 6
| Take Screenshot
|-
| 7
| Toggle stats (None, FPS, FPS + CPU)
|-
| 8
| Toggle Scaler (default, double resolution, scale2x, eagle2x)
|-
| ⌫
| Toggle Fast Forward (off, on)
|}

== Creating images of Games ==
A short how-to for doing this on Linux is available: [[Creating images of PSX games using Linux]]. On Windows you can probably rely on the common tools for creating disc images, like for example Alcohol or the likes. There were some reports in the forums that using Nero for creating images does not work.

[[Category:Emulators]]

Hardware troubleshooting

2022-12-21T22:03:55Z

Porg:

== Symptom(s) of hardware failure → Steps to analyze or fix ==

0) My Pandora doesn't turn on anymore at all.

1) Connect the DC-in cable. Does the Pandora turn on?
a) Yes → Fixed. Your battery charge was too low.
b) Give it an additional 1h. Does it go on then?
b1) Yes → Fixed. Your battery level was reduced to a critical level. It was revived.
b2) Use it for light applications while it charges.
b3) Use overclocking/heavy applications only when it charged another 1-2h, then your battery should have a stable enough charge to withstand peak levels again.

2) Try the USB-power-in. Same steps as in 1.

3) Try USB-power-in and DC-in at the same time. Same steps as in 1.

4) Take out the battery.
a) Connect only DC-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold].
b) Connect only USB-power-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold]. Additionally your DC-in capability seems damaged. For now charge via USB. Consider servicing the DC-in plug/circuitry.

5) Check your USB and DC power adaptors with a multimeter. Maybe they do not provide the proper voltage and/or current.

6) Your Pandora may fail due to a corrupted bootloader. In that state neither the status-LEDs nor the screen get turned on.

a) Try to run the [https://pyra-handheld.com/boards/threads/pandora-recovery-sd-card-image.98892/ Pandora Recovery SD-Card]. This boot disk can diagnose the device and reflash the internal NAND in needed.

7) Get the printed circuit board (PCB) out of the case. Check that the leads from the DC-in or the USB-power-in have voltage when your power plugs are connected. Maybe a solder connection got loose. Or another issue on the PCB. Consult the [https://pyra-handheld.com/boards/threads/pandora-hackers-manual.51259/ Pandora Hackers Manual]

Hardware troubleshooting

2022-12-18T21:38:05Z

Porg:

== Symptom(s) of hardware failure → Steps to analyze or fix ==

0) My Pandora doesn't turn on anymore at all.

1) Connect the DC-in cable. Does the Pandora turn on?
a) Yes → Fixed. Your battery charge was too low.
b) Give it an additional 1h. Does it go on then?
b1) Yes → Fixed. Your battery level was reduced to a critical level. It was revived.
b2) Use it for light applications while it charges.
b3) Use overclocking/heavy applications only when it charged another 1-2h, then your battery should have a stable enough charge to withstand peak levels again.

2) Try the USB-power-in. Same steps as in 1.

3) Try USB-power-in and DC-in at the same time. Same steps as in 1.

4) Take out the battery.
a) Connect only DC-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold].
b) Connect only USB-power-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold]. Additionally your DC-in capability seems damaged. For now charge via USB. Consider servicing the DC-in plug/circuitry.

5) Check your USB and DC power adaptors with a multimeter. Maybe they do not provide the proper voltage and/or current.

6) Your Pandora may fail due to a corrupted bootloader. In that state neither the status-LEDs nor the screen get turned on.

a) Try this: [https://pyra-handheld.com/boards/threads/openpandora-type-1002-doesnt-turn-on-anymore-what-to-check-how-to-repair.99796/post-1712104 Incomplete info] here. The recommendation is to use a "recovery card". Anyone reading this please update this whole step what to determine exactly and how to try to fix the situation.

7) Get the printed circuit board (PCB) out of the case. Check that the leads from the DC-in or the USB-power-in have voltage when your power plugs are connected. Maybe a solder connection got loose.

Hardware troubleshooting

2022-12-18T21:10:33Z

Porg: Trying to establish a central "Hardware troubleshooting" self-service info

== Symptom(s) of hardware failure → Steps to analyze or fix ==

0) My Pandora doesn't turn on anymore at all.

1) Connect the DC-in cable. Does the Pandora turn on?
a) Yes → Fixed. Your battery charge was too low.
b) Give it an additional 1h. Does it go on then?
b1) Yes → Fixed. Your battery level was reduced to a critical level. It was revived.
b2) Use it for light applications while it charges.
b3) Use overclocking/heavy applications only when it charged another 1-2h, then your battery should have a stable enough charge to withstand peak levels again.

2) Try the USB-power-in. Same steps as in 1.

3) Try USB-power-in and DC-in at the same time. Same steps as in 1.

4) Take out the battery.
a) Connect only DC-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold].
b) Connect only USB-power-in. Boots → Your Pandora works. Your battery has become unreliable/dead. Purchase a new battery. As of 2022-12 [https://dragonbox.de/en/accessories-for-pandora-pyra/pandora-replacement-battery.html batteries are still sold]. Additionally your DC-in capability seems damaged. For now charge via USB. Consider servicing the DC-in plug/circuitry.

5) Check your USB and DC power plugs with a voltmeter. Maybe the do not provide the proper voltage and/or current.

6) Your Pandora may fail due to a corrupted bootloader. In that state neither the status-LEDs nor the screen get turned on.

a) Try this: [https://pyra-handheld.com/boards/threads/openpandora-type-1002-doesnt-turn-on-anymore-what-to-check-how-to-repair.99796/post-1712104 Incomplete info] here. The recommendation is to use a "recovery card". Anyone reading this please update this whole step what to determine exactly and how to try to fix the situation.

Main Page

2022-12-18T20:48:36Z

Porg: /* Hardware */

__NOTOC__

::::::::::'''Openpandora''' - The pocket computer with gaming controls.
<div style="float:left">
'''Community''' 
[[IRC]] - [http://pandoralive.info/ Blog] - [[Team]] 
 
'''Input flexibility''' 
[[Keyboard]] - [[Nubs|Gaming controls]] 
[[Display|Touchscreen]] 
'''Workflow''' 
[[Power_modes#How_long_does_the_battery_last.3F|Battery life]] - Dual SD slots 
'''Audio''' 
[[Audio system|High quality sound]] 
'''Philosophy''' 
[http://en.wikipedia.org/wiki/Free_and_open-source_software Linux|Gnu] 
'''Workmanship''' 
[https://www.dragonbox.de/en/16-pandora Buy here] 
 
 
</div>
<div id="mf-home" style="float:left">
[[Image:Pandora1ghz.png | left | 400px]]
</div>
<div id="mf-home" style="float:left">
 
Built in Germany, the Pandora is a high-quality, all-purpose mobile computer offering the greatest possible degree of software freedom to a vibrant community of users and developers. We have a wide range of high quality software available on the [http://repo.openpandora.org/ repo]. 
[http://www.youtube.com/watch?v=zH-RAOrbFqs| Video demo]
</div>
 
{| width="100%"
|-

|valign="top" width="25%" style="padding:0.5em;"|
[[Image:IntroIcon.png | left | 50px]]
==Intro==
<div style="clear: both; height: 1px;"></div>
* [[Quickstart]]
* [[User manual]]
* [[Team]]
* [[Size Comparisons‏‎]]
* ‏‎[[Production Timeline‏‎]]
* [[Community Links‏‎]]
* [[Wiki TODO]]
[[Image:DesktopIcon.png | left | 50px]]
== Software ==
<div style="clear: both; height: 1px;"></div>
* [http://repo.openpandora.org/ Software repository]
* [[GUI]]
* [[OpenBox‏‎]]
* [[Minimenu]]‏‎
* [[Xfce]]
* [[Compo4All]]
* [[FlashEnv]] | [[Flashenv Compatibility List|Compatibility List]]
* [[PickleLauncher]]
* [[Backup]]
* [[GPS‏]]
* ‏‎[[Screenshot]]
* [[Wallpaper cronjob]]
* [[Port Requests]]
* ‏‎[[ResidualVM‏‎]]
* [[Software_projects|Legacy Software Projects]]

|valign="top" width="25%" style="padding:0.5em;"|
[[Image:HardwareIcon.png | left | 50px]]

== Hardware ==
<div style="clear: both; height: 1px;"></div>
* [[Pandora]]
* [[Case]]
* [[SD compatibility list]]
* [[USB compatibility list‏‎]]
* [[USB reference‏‎]]
* [[Formatting SD cards]]
* [[NAND‏]]
* [[Swap]]
* [[Display]]
* [[TV-out cable]]
* [[LEDs and backlight]]
* [[WiFi‏‎]]
* [[Bluetooth]]
* [[Audio system]]
* [[Keyboard‏]]‎
* [[Nubs‏‎]]
* [[Controllers]]
* [[Hardware defects]]
* [[Hardware troubleshooting]]
* [[Mobile Broadband]]
* [http://boards.openpandora.org/index.php?/topic/404-dvb-t-tv-on-pandora/ dvb-t] - forum link
* [[Power modes‏]]
* [[Overclocking‏‎]]
* [[Hardware Hacking‏‎]]
* [[EXT Connector]]

|valign="top" width="25%" style="padding:0.5em;"|
[[Image:SoftwareIcon.png | left | 50px]]

== Operating systems ==
<div style="clear: both; height: 1px;"></div>
* [[Boot setup]]
* [[Ångström]] (Official OS)
* [[Pandian]]
* [[Slackware]] | [[SOLEIL]]
* [[Gentoo]]
* [[Android]]
* [[‎RISC OS‏]]
* [[Basic Linux Guide‏]]
[[Image:EmulatorIcon.png | left | 53px]]

== Emulators ==
<div style="clear: both; height: 1px;"></div>
* [[Emulators]] | [[Legal Emulation Resources‏‎|Legal Resources]]
* [[Reicast]] | [[Reicast Compatibility List|Compatibility List]]
* ‏‎[[UAE4ALL‏‎]] | [http://spreadsheets.google.com/spreadsheet/pub?hl=en&key=0AuBR5X_s_5_idG92ZVQ5cEs4ZEhYTm5sSjFIcl83U2c&hl=en&gid=0 Compatibility List]
* [[DraStic]] | ‏‎[[DraStic Compatibility List‏‎|Compatibility List]]
* [[PPSSPP]] | [[PPSSPP Compatibility List|Compatibility List]]
* [[3doh]] | [[3doh Compatibility List|Compatibility List]]
* [[Mupen2.0 Compatibility List]]
* ‏‎[[PCSX-ReARMed‏‎]] | [[PSX backups]]
* [[PicoDrive]]
* [[SNES9X4P‏‎]]
* [[MAME4ALL]]
* ‏‎[[QEMU‏‎]] | [[QEMU Compatibility|Compatibility List]]
* ‏‎[[DOSBox‏]] | [[DOSBox compatibility list|Compatibility List]]

|valign="top" width="25%" style="padding:0.5em;"|
[[Image:DevelopmentIcon.png | left | 50px]]

==Hacking==
<div style="clear: both; height: 1px;"></div>
* [[Development]]
* [[Introduction to PNDs]]
* [[Libpnd hub‏‎]]
* ‏‎[[Porting to GLES from GL‏]]
* [[Porting guide‎]]
* [[GLES]]
* [[GLESGAE‏‎]]
* [[GLBasic tutorial]]
* [[SGX drivers]]
* [[SDL]]‏
* [[SDL Controls‏‎]]
* ‏‎[[Floating Point Optimization‏‎]]
* [[Assembly Code Optimization‏‎]]
* [[Compile on the Pandora]]
* [[Cross-compiler‏‎‏‎]]
* [[Make and run simple PND‏‎]]
* [[Compo4AllSDK‏‎]]
* [[Using C4A with libSparrowNet]]
* [[PXML specification]]
* [[PND repository specification]]
* [[PND management workflow‏‎]]
* [[Client Repository Communication API]]
* [[Mupen64plus dynamic recompiler‏‎]]
* [[Extend Utils]]
* [[Kernel interface]]

|}
{|
[[File:Pandora_logo_small.png|link=Logo|left|50px]]
|}
----
{|
| ''Unofficial source of info, [[Openpandora GmbH]] or [[Openpandora Ltd]] not responsible for content.
|}

USB compatibility list

2021-03-14T15:25:52Z

Porg: /* Video display device */

This is a list of USB devices that have been tested on the Pandora. If the device you want to know about isn't listed here, don't worry! Just go to [[USB_reference|the USB reference page]], look up the specs of your device, and you may be able to figure out if it's compatible.

= Troubleshooting =

Each type of device will have its own unique way to troubleshoot.

But here are some general tips:

* Is USB-Host enabled?
* check <tt>lsusb</tt>
* check <tt>dmesg</tt>

When asking for help on [http://boards.openpandora.org/index.php?/forum/8-support/ the forums support board], be sure to post both your <tt>lsusb</tt> and <tt>dmesg</tt>.

Because <tt>dmesg</tt> output is very long, you need to paste it within [spoiler] tags like this:

[spoiler]
(paste your dmesg in here)
[/spoiler]

An easy way to get your <tt>dmesg</tt> so you can easily copy and paste it, is:

dmesg|leafpad

<tt>leafpad</tt> will open with the output of <tt>dmesg</tt>.

If you have no networking on your palmtop, you can send the information to a text file like this:

cd (your storage card)
dmesg>textfile.txt
sync

Then you can remove your card (if no programs are using it or PNDs are running on it) and bring it to a card reader on your desktop.

= Networking =

Please see the [[Mobile Broadband]] page for tips on how to get these working, as well as [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/ this tutorial] from the GP32X forum.

== HSDPA (3G) Modems ==

Please note that many (if not all) USB 3G modems need modemmanager to be installed for switching from mass storage mode to serial communications mode. When first plugged in, most 3G USB modems claim to be a mass storage device and offer, on its built-in flash, drivers and connectivity software to be installed. Mostly this is only for Windows and Mac, so for the Pandora this is not useful. modemmanager instantly takes care of toggling the mode, so that when you plug in the modem, after a few seconds or maybe half a minute modemmanager has switched the modem to communications mode and NetworkManager is able to use it.

If you are using a Firmware before HF7 (or one of its Alpha/Beta versions) you have to install modemmanager. To do so, connect your Pandora to the Internet, open a terminal and, as a super user, intall it via opkg by entering the commands:

:sudo opkg update
:sudo opkg install modemmanager

'''Note:''' If you are using a firmware more recent than "Zaxxon" Hotfix 6 (starting with HF7) you do not have to follow the steps outlined above since modemmanager comes preinstalled.

'''Note 2:''' After plugging in the USB 3G modem, it may take some time until NetworkManager is able to use the modem. Wait for at least half a minute, until you give up and report that the modem doesn't work.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| ZTE K3565-Z / MF626 / MF627 / MF636
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__956513] [http://boards.openpandora.org/index.php?/topic/7226-superzaxxon-beta-11-released/page__pid__127881#entry127881]}}
| A how-to by shideneyu for this modem can be found [http://www.pandorawiki.org/ZTE_K3565Z_3G_USB_Modem here]
|-
|-
| BandLuxe C270
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| A how-to by relliker for this modem can be found [http://www.pandorawiki.org/BandLuxe_C270_3G_USB_Modem here]
|-
| Huawei E156G
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/52827-3gumts-usb-dongle/page__view__findpost__p__835681]}}
|
|-
| Huawei E160
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong. This one definitely needs modemmanager. After installing modemmanager, it works flawlessly.
|-
| Huawei E160E
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong.
|-
| Huawei E1750
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__939350]}}
|
|-
| [[wikipedia:Huawei E220|Huawei E220]]
| Not required
| Standard-A
| USB 1.1
| 500mA
| Standard-A port via High Speed hub
| {{No|Not on new kernels.}}
| The successful Pandora E220 tests were done by DJWillis on an old kernel (long before Pandora shipped). It seems that they are NOT working any more. Also tested on Linux (was it working?) This entry originally said 250mA, but there is no source and current sources say 500mA.
|-
| Huawei E3531
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Need recent USB_ModeSwitch compiled and installed, see (http://www.draisberghof.de/usb_modeswitch/); then type "usb_modeswitch -W -I -v 12d1 -p 15ca -M 55534243123456780000000000000011062000000101000100000000000000" to switch to modem mode (lsusb should change from 12d1:15ca to 12d1:1506). Enable automatic modem switch: sudo nano /etc/modutils/mobilestickserial and enter "usbserial vendor=0x12d1 product=0x15ca", sudo nano /etc/udev/rules.d/999-mobilestick.rules and enter "SUBSYSTEM=="usb", SYSFS{idProduct}=="15ca", SYSFS{idVendor}=="12d1", RUN+="/usr/sbin/usb_modeswitch -W -I -v 12d1 -p 15ca -M 55534243123456780000000000000011062000000101000100000000000000"", off course checking usb_modeswitch path, in this case /usr/sbin
|-
| 4G-Systems XS Stick P14
| Not required (usbserial module)
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__937681]}}
| Requires usbmodeswitch program.
|-
| iPhone 3GS (Probably also 1G/3G)
| ipheth
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Maybe|Should work in Angstrom with some work.}}
| Requires a good bit of dependencies to get working. Tested with Debian from SD, but should work in Angstrom with some work. The ipheth wwan0 device only provides a connection over the 3G modem, even if you're connected to a wifi network. I used the iproxy and SSH tunneling method with proxychains to get to the wifi network.
|-
| HTC Desire
| not required
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Yes}}
| Requires internet connection sharing to be enabled from the phone.
|-
| Samsung Galaxy Ace 2
| not required
| Micro-B female
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| Tested with phone firmware from T-Mobile (July 2012). Connect the USB cable, enable USB tethering on the phone, and connect to lfupdown on Pandora NetworkManager. Works with 3G and wifi.
|
|-
| Firefox Flame
| not required
| Standard-A -> Micro-B
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Tested with phone with software Boot2Gecko 3.0.0.0-prerelease. Connect the USB cable, enable USB tethering on the phone, and connect to ifupdown on Pandora NetworkManager. Works with 3G and Wi-Fi.
|}

== USB to Ethernet adapters ==

To enable USB Ethernet adapters on the Pandora, you may need to left-click the networking icon on the panel in Xfce, and select "Ifupdown (bnep0)".

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Mbps
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Apple USB Ethernet Adapter MB442Z/A
|
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Reportedly uses an ASIX AX88xxx chipset.
|-
| Apple USB Ethernet Adapter model A1277
|
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 05ac:1402 Apple, Inc.
|-
| ASUS USB Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0b95:7e2b ASIX Electronics Corp. AX88772B
|-
| Conrad 3-Port-USB-Hub und Netzwerk-Adapter
|
| Not required
| Standard-A
| USB 2.0
| A lot! {{HideableNotes|50% of battery charge only brings you 2h40min (min brightness, no other devices attached)}}
| Standard-A port
| {{Yes}}
| Has a 3port USB Hub included. External power supply can (and should) be attached, not included though. ASIX Chipset. 20€ @ [http://www.conrad.de/ce/de/product/976406/NOTEBOOK-MINI-DOCKINGSTATION-USBRJ45/SHOP_AREA_32315&promotionareaSearchDetail=005 Conrad Electronics]. Not tested in Linux.
|-
| Logitec USB 2.0 LAN-GTJ/U2B Ethernet adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) 1000Mbps=350mA 100Mbps=230mA 10Mbps=220mA(documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.logitec.co.jp/products/lan/langtju2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2B Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 100Mbps=170mA 10Mbps=210mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp.[http://www.logitec.co.jp/products/lan/lantxu2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 300mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp. USB hub current: 100mA (lsusb) 200mA (documentation). [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php] [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Wii USB 2.0 10/100M adapter (use [http://www.asix.com.tw/products.php?op=pItemdetail&PItemID=86;71;101 ASIX AX 88772 USB 2.0 chip])
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772. [http://www.dealextreme.com/details.dx/sku.5926 This clone from DealExtreme] works too.
|-
| Connectland USB 2.0 10/100M Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772 - Works fine, Sometimes a reboot is necessary (ZaxxonHF5RC1).
|-
| Belkin Gigabit USB 2.0 Network Adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| The shape of it make is a bit awkward to fit if you connect it directly, but it has a short adapter cable. I only get ~95Mbit on a gigabit network, but then the pandora's cpu maxes out. (it may be that the driver/usb stack isn't very well optimized), has horribly bright blue LEDs.
|-
| MosChip MCS7830 USB 10/100 Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Kernel module: mcs7830.
|-
| EU.MARK USB 10/100M RJ45 Ethernet Network Adapter Dongle
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| USB ID: 9710:7830 - bought from [http://www.dealextreme.com/details.dx/sku.22684 DealExtreme]
|-
| Digitus DN-10050 Fast Ethernet USB Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| MosChip MCS7830-based adapter. USB ID 9710:7830.
|-
| Edimax EU-4230 Fast Ethernet USB Adapter with 3-port USB hub [http://edimax.ie/images/Image/datasheet/USB/EU-4230/EU-4230_Datasheet.pdf]
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Ethernet USB ID 0b95:772a ASIX Electronics Corp. 3-port USB2.0 hub USB ID 0409:005a NEC Corp. Optional power adapter for USB hub.
|-
| Peabird USB v2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Consumes a lot of current. Fragile, the protective plastic cord cracked after one month. Hot. A blue light a bit too flashy. Definitely avoid this model.
|-
| SIIG JU-NE0012-S1 USB 2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16812191163 Newegg]
|-
| TRENDnet USB to Gigabit Ethernet Adapter TU2-ETG
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) Dormant: 5mA Static: 91mA Working: 131mA (documentation)
| Standard-A port
| {{Yes}}
| Rev. 2.0R ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.trendnet.com/products/proddetail.asp?prod=275_TU2-ETG&cat=42] Rev. 2.0R is white, previous versions are blue and consumes more current. The documentation's current draw are reported for 10 and 100Mbps.
|-
| Novatel Wireless Jetpack 4620L
|
| cdc_ether
| Standard-A
| USB
| High drain; 95% charge = 6:00 battery life.
| Standard-A port
| {{Yes}}
| This is a LTE/EVDO/CDMA/HSPA/UMTS/EDGE/GPRS Wifi Hotspot device; Device is registered as a USB Ethernet device when connected through USB tethered (as opposed to Wifi) connection. USB ID 1410:b008
|-
| LOGILINK UA0174A Fast Ethernet USB Adapter with 3-port USB hub
| 10/100
| Not required
| Standard-A
| USB 2.0
| about 300mA
| Standard-A port
| {{Yes}}
| This is a combined USB 2.0 3Port Hub and USB to Ethernet adapter. ID 0b95:772b ASIX Electronics Corp. AX88772C; bought at [http://www.reichelt.de/Netzwerkkarten/LOGILINK-UA0174A/3//index.html?ACTION=3&GROUPID=5822&ARTICLE=132333&SEARCH=usb%20ethernet&OFFSET=16&WKID=0&]
|}

== USB to serial adapters ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| pl203
| usbserial
| Standard-A
| USB 1.1
| 100mA. A powered hub is needed.
| Standard-A port
| {{Yes}}
| A powered hub is needed. Plug the device, then load USB modules. ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port.
|-
| SparkFun FTDI Basic Breakout
| not required
| Mini-B female
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| Tested the variant sold by eBay seller "goodlucksell".
|}

== USB WiFi adapters ==

The Pandora stock kernel may not come with all wireless driver support outside of the internal WiFi chip. Sometimes, the only way you'll get wireless working is to build your own kernel with it included or try [http://wireless.kernel.org/en/users/Download compat-wireless].

As for hofix 6a4 compat-wireless seems to be present in the kernel out of the box, so one can build a USB wireless driver for Pandora following this [http://boards.openpandora.org/index.php?/topic/5140-solvedbuilding-a-usb-wifi-driver/page__view__findpost__p__89280 algorithm]

As for [[hotfix 6]] Release Candidate the kernel includes drivers for these Realtek chips: RTL8712/8188/8191/8192SU/8192CU

See also [http://boards.openpandora.org/index.php?/topic/7160-micro-wifi-dongle/ this thread] on the forums for the latest.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| Advance Mini Wireless N150
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| There's a little hole on it, so it's useful for attaching it to the OP.
|-
| ASUS WL-167G v2
| rt73usb + rt2x00usb + rt2x00lib
| Standard-A
| USB 2.0
| 300mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 0b05:1723 ASUSTek Computer, Inc. WL-167G v2 802.11g Adapter [Ralink RT73]. Works pretty fine on Linux PC.
|-
| Belkin N1 Wireless USB Adapter (F5D8051) ("Ver. 2053") (MARVELL v1021)
| N/A
| Standard-A
| USB 2.0
| {{Unknown}}
| No connection was attempted.
| {{No|No native driver support and ndiswrapper obviously won't work.}}
| There's a previous revision of this dongle which is supposed to have a Ralink chip, but they revised it and put a different chip inside. Reported (by whom?) to work with ndiswrapper and works in Linux.
|-
| Belkin Surf micro
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Cisco/Linksys AE1000 High Performance Wireless-N USB Adapter
| rt3572sta (RT3572USB)
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A (Standard-A port?)
| {{Yes|Works with a modified driver.}}
| (Compiled module for pandora:[http://boards.openpandora.org/index.php?/topic/1992-linksys-ae1000-usb-wifi/ pandora forum]) Download the driver from [http://www.ralinktech.com/support.php?s=2 ralink's driver site], edit ./common/rtusb_dev_id.c, before "#endif // RT2870" add "{USB_DEVICE(0x13B1,0x002F)},", compile.' Reported (by whom?) to work in Linux.
|-
| D-Link WIRELESS G USB ADAPTER DWL-G122 rev.E1 F/W 5.00
| rt2870sta + rt2800usb + rt2800lib
| Standard-A
| USB 2.0
| 450mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 07d1:3c0f D-Link System AirPlus G DWL-G122 Wireless Adapter(rev.E) [Ralink RT2870]. Works pretty fine on Linux PC.
|-
| Digitus Wireless 150N USB 2.0 Adapter
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| Bundled with a non-WiFi Pandora coming from Craig's shop
|-
| Edimax EW-7811Un
| rtl8192cus
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Havit HV-WF15
| n/a
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since SuperZaxxon}}
|-
| Netgear WNA1000M
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Thomson WLG-1500A
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|Doesn't work.}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter
|-
| TRENDnet TEW-424UB V2
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|lsusb shows it, but no module is loaded}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter. Same behavior on a PC.
|-
| Alfa Network AWUS036H 1000mw
| RTL8187
| IEEE 802.11b/g
| USB 2.0
| ?
| USB A
| {{Yes|Yes}}
| can be found on ebay; tested with Beta 3
|-
| TP-Link 150Mbps Mini Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN723N. Tested with WPA2. Works out of the box. Cheap to buy (£6.99 from pcworld in the UK).
|-
| TP-Link 150Mbps '''Nano''' Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN725N. Works out of the box. From Reichelt.de. Claims to be RaspberryPi compatible on their website.
|-
| [http://www.tp-link.com.de/products/details/?model=TL-WN823N#spec TP-Link 300Mbps '''Mini''' Wireless N]
| Unknown
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN823N. Works out of the box. Is also RaspberryPi compatible. Has been tested.
|-
| TP-Link Atheros AR9170
| carl9170-1.fw
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{Yes|Yes}}
| Model No TL-WN821N. Works out of the box. ID 0cf3:1002
|-
|}

== DVB/TNT/TDT ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Module(s)
! Firmware
! Additional comments
|-
| AVerMedia AVerTV Volar Green HD
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| Should work
| af9033 tda18218
| dvb-usb-af9035-02.fw
| ID 07ca:a835 AVerMedia Technologies, Inc.
HD/PRO (A835)
|-
| AVerMedia AVerTV Volar Video Capture
| Standard-A
| USB 2.0
| Reported as 0mA. More likely to be 500mA
| Standard-A port
| ?
| ?
| ?
| ID 07ca:4830 AVerMedia Technologies, Inc.
H830
|-
| Hauppauge WinTV aero
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes|Yes}}
| smsmdtv
| sms1xxx-hcw-55xxx-dvbt-02.fw
| ID 2040:b900 Hauppauge . Also works on the mini-usb port.
|-
| Hauppauge WinTV-HVR 930C
| Standard-A
| USB 2.0
| 150mA (idle)
| Standard-A port
| {{No}}
| em28xx xc5000
| dvb-usb-hauppauge-hvr930c-drxk.fw dvb-fe-xc5000-1.6.114.fw
| ID 2040:1605 Hauppauge . Not able to get it to work yet. Embedded Remote control ID: 0525:a4aa
|-
| ITE 9135
| Standard-A
| USB 2.0
| 515mA
| Standard-A port
| {{Yes}}
| rtl2832 rtl2830
| dvb-usb-it9135-02.fw
| Gets very hot
|-
| MSI Digi Vox Min
| Standard-A
| USB 2.0
| ?
| Standard-A port
| {{Yes|Yes}}
| ?
| ?
| Realtek rtl2832u chipset
|-
| Realtek RTL2832U
| Standard-A
| USB 2.0
| 460mA
| Standard-A port
| {{Yes}}
| dbv_usb_af9035 dbv_usb_v2
| dvb-usb-it9135-02.fw
| idVendor=0bda, idProduct=2838
|-
| Realtek RTL2832UHIDIR
| Standard-A
| USB 2.0
| 464mA
| Standard-A port
| {{Yes}}
| dbv_usb_rtl28xxu
| dbv_usb_rtl28xxu.ko rtl2830.ko
| idVendor=0bda, idProduct=2838
|-
| Velleman Mini USB DBV-T receiver
| Standard-A
| USB 2.0
| 438mA
| Standard-A port
| {{Yes}}
| ?
| dvb-usb-it9135-01.fw
| remote control: rc-it913x-v2
|-
|}

= Storage =

== External Hard Disk Drives ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! style="min-width: 120px" | Works on Pandora
! Additional comments
|-
| Freecom 250GB 2.5" portable
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Inside it's a Samsung Model HM251JX. {{HideableNotes|So I guess anything based on that will also work OK.}}
|-
| (Intenso)® 2.5" MEMORYSTATION 1TB
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
|
|-
| LaCie Rikiki 250GB USB 2.0 2.5" Hard Drive
| Not required
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port via powered High Speed Hub
| {{Partial|Not when unpowered, needs testing with a powered hub}}
| Not only does it fail to spin up, but it causes the Pandora's screen to pulsate wildly, much like an old CRT would if you placed a speaker or a magnet near to it. Not tested with a powered hub.
|-
| Seagate Seagate® Expansion™ External Drives
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{No}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14781-hitnrun/ Hitnrun]. "Isn't even detected in lsusb (drive powered by external power source)"
|-
| Verbatim 250GB Model #47580 Hard Drive
| Not required
| Direct
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877512 almatuk]. {{HideableNotes|"Watched videos directly from it at full speed, no need for powered USB hub. Had issues playing roms directly off it however as it was formatted NTFS. I'm sure if I formatted to FAT32 these would disappear."}}
|-
| Western Digital 160GB Elements External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| standard-A port via powered High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB Elements Portable USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or standard-A port via High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB My Passport Essential USB 2.0 2.5" Hard Drive
| Not required
| {{Unknown|Direct?}}
| USB 2.0
| {{Unknown}}
| {{Unknown|Direct?}}
| {{Partial|Maybe}}
| Tested by TheDarkSpectrum48K. The first time it [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877386 "works perfectly!"]. The second time [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__882635 it didn't work].
|-
| Western Digital 400GB My Passport Essential USB 2.0 2.5" HDD model WDME4000TE
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14534-peca/ Peca].
|-
| Western Digital 500GB Elements Portable External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. {{HideableNotes|The USB cable that came with it was bad, so I used another one.[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949863]}}
|-
| Western Digital 500GB My Passport Essential External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works fine. {{HideableNotes|Came pre-formatted in NTFS, but should work if you downloaded the community codec pack. It said 1TB on the packaging, but there was 465GB free space, so I'm pretty sure it was actually the 500GB one.}}[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949645]
|-
| Western Digital 1TB My Passport Essential SE External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or through powered High Speed Hub
| {{Yes}}
| Tested by [http://http://www.gp32x.com/board/index.php?/user/19191-mycohl/ Mycohl]. {{HideableNotes|Externally powered hub recommended to conserve battery power.}}
|-
| Western Digital Elements 2TB 3.5" Hard Drive Model:WDBAAU0020HBK
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://boards.openpandora.org/index.php?/user/430-kilowatt/ kilowatt].
|}

== DVD/CD Drives ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Lite-On EZ-DUB DVD/CD Multi-Recorder (Model eZAU120)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter - DC 12V 1.8A
| Standard-A port
| {{No}}
| Works in Linux.
|-
| Memorex 20x Multi Format DVD Recorder External - DVD±RW (±R DL)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter
| Standard-A port
| {{Yes}}
|
|}

= Video display device =

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
| Tritton see2 usb 2.0 to SVGA adapter
| sisusb
| USB
| USB 2.0
| {{Unknown|High {{HideableNotes|Reduces Pandora's battery life in half (10h → 4h)}}}}
| VGA (D-SUB)
| {{Partial|Yes, but has performance issues.}}
| Needs to be integrated with preferences. {{HideableNotes|Currently I (who?) must edit xorg.conf and mess with xinerama.}} Good for presentations, dragging a window is bearable, but hi-res video is slow. Works in Linux without any issues.
|-
| DisplayLink usb 2.0 to SVGA adapter WS Tech USB-DVI
| udlfb
| USB
| USB 2.0
| 500mA
| VGA (D-SUB)
| Yes
| 17e9:0198 DisplayLink. No hub needed. Module and userspace here:
git clone http://git.plugable.com/webdav/udlfb/
git clone http://git.plugable.com/webdav/xf-video-udlfb/
|-
| Plugable DisplayLink UGA-165
| ?
| Mini-B female
| USB 2.0
| ?
| DVI/VGA/HDMI
| {{Yes}}
| In /etc/X11, copy xorg.conf.DisplayLink to xorg.conf then '''log out''' with the device attached [http://pandoralive.info/?p=3423]
Remark by [[User:porg|porg]] without having tested it myself. I guess quite ok for static content, but vivid/dynamic content may suffer lag, as the [https://plugable.com/products/uga-165/ official product page] says:
"USB speed limitations prevent smooth playback with full-screen HD videos, and games suffer similar performance limitations or don't work at all since no direct hardware access (DirectX) is possible."
|-
| Magic Control Technology Corp. Trigger II External Graphics
| sisusb
| USB
| USB 2.0
| 500mA
| ?
| ?
| ID 0711:5200 Magic Control Technology Corp. A kernel recompile is needed. In /usr/src/linux/drivers/usb/misc/sisusbvga , edit sisusb.c , and add

{ USB_DEVICE(0x0711, 0x5200) },

in the list around line 3250
Get the latest xf86-video-sisusb driver here:
http://xorg.freedesk...ividual/driver/

|}

= Video capture devices =

== Webcams ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Exoo No Driver/USB 2.0 Webcam (Model No.: M053)
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| Bought from [http://www.dealextreme.com/details.dx/sku.14991 DealExtreme]. Works in Linux.
|-
| Logitech Quickcam Communicate Deluxe
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| USB ID: 046d:0992, works though [http://linux-uvc.berlios.de/ uvcvideo]. Works in Linux.
|-
| Logitech Webcam c210
| Not required
| Standard-A
| USB 2.0
| 170mA
| Standard-A port
| {{Yes}}
| ID 046d:0819 <unnamed>. Video and Audio recognized, tested to work.
|-
| Logitech HD Webcam C270 720p
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0825 Logitech, Inc. Audio recognized, but not tested. More info to come. Works in Linux.
|-
| Logitech HD Webcam Pro 9000
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0990 Logitech, Inc. Audio recognized, but not tested. Great Picture! Works in Linux.
|}

= Audio devices =

== Microphones/recorders ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.bluemic.com/yeti/] Blue Yeti
| not required
| standard-A
| unknown
| unknown
| standard-A port via High Speed USB hub
| {{unknown|Not thoroughly tested.}}
| Very roughly tested 2012-06-13 by [[user:spiralofhope|spiralofhope]] using Mumble. More testing required. {{HideableNotes|The system recognizes the Yeti, and it appears in Mumble's list of available devices, but the audio wizard doesn't show the Yeti as having input. Additional troubleshooting is required, as is checking the manual/company website for missing information.}}
|-
| [http://www.zoom.co.jp/english/products/h2/] Zoom H2 Handy Recorder
| not required
| standard-A
| USB 1.1
| 300mA
| standard-A port via High Speed USB hub
| {{Yes|Yes, needs a USB hub.}}
| Can record into Audacity, but won't be recognized unless connected through USB hub.[http://www.gp32x.com/board/index.php?/topic/59301-audacity-1-3-12/page__view__findpost__p__947602].
|}

== MIDI controllers ==

EvilDragon bundled the usb MIDI class drivers in the default firmware image, therefore ANY class-compliant MIDI device should work with the Pandora, out of the box.[http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Akai LKP25
| Not required
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]}}
|
|-
| M-Audio MIDISPORT 2x2 Anniv
| Not required
| {{Unknown}}
| {{Unknown}}
| 400mA
| {{Unknown}}
| {{Unknown}}
| ID 0763:1050 Midiman. High current draw!
|-
|}

== USB audio controllers ==

Some are "professional soundcard"; see [http://en.wikipedia.org/wiki/Sound_card#Professional_soundcards_.28audio_interfaces.29 definition on Wikipedia].

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Cakewalk UA-1G
| not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0582:00e9 Roland Corp. This device may be similar to older Edirol/Roland USB audio devices. Runs and record under Slackware. Jack audio server realtime recording works. Recognized but not tested under official OS. A hub, powered or not, is needed.
|-
| Connectland AUDIO ADAPTER
| not required
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes}}
| ID 0d8c:000c C-Media Electronics, Inc. Audio Adapter . CMedia CM108 Virtual 7.1 Channel Sound. Has vol +, vol -, mute headspeaker, mute mic buttons. Mini-jack audio in and out. A non-powered hub is needed.
|}

= Input devices =

Any HID ([http://en.wikipedia.org/wiki/Human_interface_device Human Interface Device]) compliant keyboard, mouse or game controller should work on the Pandora. Most of those device are low speed or full speed USB device and will need to be connected though either a [[USB_reference#OTG host mode|USB OTG adapter/cable]] or a [[USB reference#What’s all this stuff about USB 1.1 and USB 2.0? Isn’t USB, uh, universal?|USB2 hub]] in order to work on the Pandora.

== External Game Controllers ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| 2-TECH SNES-to-USB adapter
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| USB description is "HuiJia USB GamePad", <tt>lsusb</tt> calls it "0e8f:3013 GreenAsia Inc."
|-
| USB Super RetroPort (SNES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=29 RetroZone]. Works in Linux.
|-
| USB RetroPort (NES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=28 RetroZone]. Works in Linux.
|-
| Trio Linker Plus II (PlayStation,-GameCube,-and-Dreamcast-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.play-asia.com/paOS-13-71-6m-49-en-70-1zfv.html Play-Asia]. Works in Linux.
|-
| NAZAR V47 USB Force Feedback Vibrating Gamepad Controller for PC
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.24551 DealExtreme]. Works in Linux.
|-
| 10-Fire-Button Double Vibration Feedback USB PC Arcade Joystick
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.27821 DealExtreme]. Works in Linux.
|-
| Official PlayStation 3 controller
| Not required
| Standard-A
| Full speed
| {{Unknown}}
| USB A To Mini B Cable via High Speed Hub
| {{unknown}}
| This is for USB not bluetooth compatibility. Sixaxis and DualShock not tested. Works in Linux.
|-
| Saitek PLC Cyborg Force Rumble Pad (P2500) - 06a3:ff0c
| {{unknown}}
| Standard-A
| {{unknown}}
| 5V
| Standard-A port via High Speed Hub
| {{Unknown|Not fully tested}}
| Partial test attempted 2012-06-24 by [[user:spiralofhope|spiralofhope]]. lsusb lists it. More testing required. {{HideableNotes|A gamepad testing procedure needs to be defined. See [[Joystick testing]].}}
|-
| Thrustmaster Firestorm Digital 3 Gamepad
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| ID 07b5:0213 Mega World International, Ltd Thrustmaster Firestorm Digital 3 Gamepad.
|-
| Wired Xbox 360 Controller
| xpad module
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| This also includes gamepads for PC that needs the Windows Xinput driver. Such gamepads include the Logitech Chillstream. Works in Linux.
|-
| WiseGroup.,Ltd SmartJoy Dual PLUS Adapter (dual PSX to USB joypad adapter)
| Not required
| Standard-A
| USB 1
| 100mA
| Standard-A port via USB 1-compatible High Speed Hub
| {{Yes}}
| ID 6677:8802. Works in Linux.
|-
| Logitech Cordless RumblePad 2
| Not required
| Standard-A
| Low speed
| 100mA
| Standard-A port via High Speed Hub
| {{Yes}}
| Product-ID: 0xc219, Vendor-ID: 0x046d (Logitech Inc.), [http://www.logitech.com/support/287 Official product support website], All buttons worked fine in PCSX, analog sticks not tested, but likely work"
|-
|}

== Touchpads ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.logitech.com/en-us/mice-pointers/mice/devices/8417 Logitech Wireless Touchpad]
| Not required
| Standard-A
| {{Unknown}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| Left and right four-finger swipes aren't mapped to anything by default in XFCE. They can be mapped as keyboard shortcuts.
|}

== Graphics tablets ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Works on Pandora
! Additional comments
|-
| Bamboo Multitouch
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__881806]}}
| It's not known if this works in Linux.
|-
| Genius Tablet
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes, [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__883140 via USB hub]}}
| It's not known if this works in Linux.
|-
| Wacom CTH-460
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__924422]}}
| Would need a patched driver to work. It's not known if this works in Linux.
|-
| Wacom Volito2 Tablet (Model: CTF-420)
| Not required
| Standard-A
| Low speed
| 40mA [http://www.my-volito.com/volito/specs.asp?lang=en]
| {{No}}
| USB ID: 056a:0062
|}

== Mice ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Works on Pandora
! Additional comments
|-
| Apple Mouse (M5769)
| USB
| {{No}}
| Seems to disable USB port, reboot afterwards required
|-
| Apple Mouse with Scroll Ball (A1152)
| USB
| {{Yes|Yes, needs a USB hub.}}
|
|-
| Cherry Ghostcord [http://www.amazon.de/Cherry-M85-26005DE-2-B-Unlimited-Home-Rechargeable/dp/B001EDSE0U/ref=tag_stp_s2_edpp_url]
| USB
| {{Yes|Yes, needs a USB hub.}}
| Part of a bundle with keyboard and a USB dongle for the connetion. With the dongle on the hub both devices work just fine (tested in XFCE)
|}

= Infrared =

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| TopSeed remote (branded ''Sapphire'' or ''CyberLink'')
| hid_topseed (added SZ 1.73)
| Standard-A
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| Some of the special buttons don't generate any key event.
|-
| Dangerous Prototypes IRToy
| cdc_acm (included)
| Mini-B female
| USB 1.1
| 200mA
| Standard-A port with hub
| {{Yes}}
| Can send and receive raw IR codes via the virtual serial connection. No application support yet.
|}

= Electronics development =
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Microchip PICkit 2
| not required
| Mini-B female
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| The pk2cmd application compiles easily.
|-
| Arduino Uno
| not required
| Standard-B female
| USB 1.1
| 50mA
| OTG port
| {{Yes}}
|
|-
| Arduino Leonardo
| not required
| Micro-B female
| USB 1.1
| 50mA
| Standard-A port with hub
| {{Yes}}
| The Arduino PND failes to compile sketches for the Leonardo, but a pre-programmed board can still communicate with the Pandora. The Leonardo makes an incorrect USB current request, but this can be reprogrammed if you want to use it on the OTG port - in Arduino's ''USBCore.h'', change ''USB_CONFIG_POWER_MA(500)'' to 100.
|}

= Connectors, adapters, and hubs =

This section is intended as a general guide. Items in this section are standard USB accessories, so drivers are not required. Compatibility with Pandora is assumed. Please note that any external product links are provided for reference only, and are not an endorsement.

== OTG (On The Go) Adapters ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Generic adapter
| {{No}}
| [http://shop.ebay.com/?_from=R40&_trksid=p3907.m38.l1313&_nkw=usb+otg+host+cable&_sacat=See-All-Categories Find on eBay] [http://www.amazon.co.uk/s/ref=nb_ss_ce?url=search-alias%3Delectronics&field-keywords=OTG+Cable+Adapter&x=3&y=23 Find on Amazon] These links are not 100% accurate. Check for `mini-a`, and on eBay, the price is higher by about $8.
|-
|Hama 00074214
| {{Yes}}
|[http://www.hama.de/00074214/hama-mini-usb-adapter-mini-usb-a-plug-usb-a-socket-015-m Manufacturer Page]
|-
| Nokia USB OTG adapter
| {{Yes}}
| [http://www.electronicproductonline.com/catalog/product_info.php?cPath=35_67&products_id=2043 Electronic Product Online]
|}

== Compact USB Hubs ==

Be sure to enable USB-host!

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Griffin SmartShare USB [http://www.griffintechnology.com/products/smartshare-usb]
| {{No}}
|
|-
| Belkin F5U415 4 Port USB 2.0 Swivel Hub [http://catalog.belkin.com/IWCatProductPage.process?Product_Id=377085]
| {{No}}
| Comes with an optional power adapter.
|-
| Belkin F5U700 USB 2.0 7-Port Lighted Hub [http://www.belkin.com/uk/support/article/?lid=enu&pid=F5U700ea&aid=10289&scid=947]
| {{Yes}}
| Tested 2012-06-16 by [[user:spiralofhope|spiralofhope]] both with and without its power adapter.
|-
| Belkin F5U701 USB 2.0 7 Port Mobile Hub [http://www.belkin.com/IWCatProductPage.process?Product_Id=369788]
| {{Yes}}
| Tested by pabloh. Comes with an optional power adapter.
|-
| ID 0e8f:0016 GreenAsia Inc.
| {{No}}
| Tested by tsh. Labeled as high speed. Bought from ebay.
|-
| ID 05e3:0608 Targus with Genesys Logic 4 Port USB 2.0 Hub
| {{Yes}}
| Tested by Kazuki. Works.
|-
|Trust 4 port netbook hub ID 05e3:0608
| {{Yes}}
| Tested by tsh. Bought from [http://www.amazon.co.uk/gp/product/B0025X16AS Amazon].
|-
| High Speed 4 Port Mini USB 2.0 Hub for Laptop PC (non powered)
| {{Yes}}
| Octopus-style small cheap unpowered USB hub. Bought from [http://cgi.benl.ebay.be/ws/eBayISAPI.dll?ViewItem&item=270538502843 ebay]
|-
| Keeptech USB 2.0 Hub (7 Ports) with Power Adapter, KT-UH703 [http://www.keeptech.com/books_show.php?id=144]
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works powered or unpowered.
|-
| Logitech Premium 4-Port USB Hub [http://www.logitech.com/en-in/notebook-products/usb-hubs/devices/3048]
| {{Yes}}
|
|-
| LUPO 7-port USB 2.0 Hub (cheap octopus type which can be powered as there is dc socket)
| {{Partial|Yes. {{HideableNotes|Can use a power supply but wasn't tested with one.}}}}
| Tested by kilowatt. Bought from [http://www.amazon.co.uk/gp/product/B003BVDABG/ref=oss_product from amazon uk]
|-
| LogiLink USB 2.0 Hub 4-Port UA0086 [http://www.logilink.eu/showproduct/UA0086.htm]
| {{Yes}}
| Tested by Jones. Comes with an optional power adapter.
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php]
| {{Yes}}
| See [http://pandorawiki.org/USB_compatibility_list#USB_to_Ethernet_adapters USB to ethernet adapters] for more details. USB 1 devices work perfectly. Also available as other brands: [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Rosewill RHB-220 4-port USB 2.0 Hub
| {{Yes}}
| Tested by Tyrant1919. Unpowered. Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16817182168 Newegg].
|-
| i-rocks SLEEK HUB USB 2.0 4 Ports Hub [http://www.i-rocks.com/Product_detail.aspx?CLASS_ID=1036&PRODUCT_ID=1080]
| {{Yes}}
| Comes with an ac adapter, but can be used without. USB 1 devices work perfectly.
|-
| MSI StarHub201
| {{Yes}}
| Testet by mclien with keyboard and mouse in XFCE, unpowered, not on the MSI site (discontinnued, guess) [http://alatest.dk/anmeldelser/hubs-og-switches/msi-star-hub-201/po3-34222999,42/]
|}

[[Category:USB]]
[[Category:List]]

USB compatibility list

2021-03-14T15:21:45Z

Porg: /* Video display device */

This is a list of USB devices that have been tested on the Pandora. If the device you want to know about isn't listed here, don't worry! Just go to [[USB_reference|the USB reference page]], look up the specs of your device, and you may be able to figure out if it's compatible.

= Troubleshooting =

Each type of device will have its own unique way to troubleshoot.

But here are some general tips:

* Is USB-Host enabled?
* check <tt>lsusb</tt>
* check <tt>dmesg</tt>

When asking for help on [http://boards.openpandora.org/index.php?/forum/8-support/ the forums support board], be sure to post both your <tt>lsusb</tt> and <tt>dmesg</tt>.

Because <tt>dmesg</tt> output is very long, you need to paste it within [spoiler] tags like this:

[spoiler]
(paste your dmesg in here)
[/spoiler]

An easy way to get your <tt>dmesg</tt> so you can easily copy and paste it, is:

dmesg|leafpad

<tt>leafpad</tt> will open with the output of <tt>dmesg</tt>.

If you have no networking on your palmtop, you can send the information to a text file like this:

cd (your storage card)
dmesg>textfile.txt
sync

Then you can remove your card (if no programs are using it or PNDs are running on it) and bring it to a card reader on your desktop.

= Networking =

Please see the [[Mobile Broadband]] page for tips on how to get these working, as well as [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/ this tutorial] from the GP32X forum.

== HSDPA (3G) Modems ==

Please note that many (if not all) USB 3G modems need modemmanager to be installed for switching from mass storage mode to serial communications mode. When first plugged in, most 3G USB modems claim to be a mass storage device and offer, on its built-in flash, drivers and connectivity software to be installed. Mostly this is only for Windows and Mac, so for the Pandora this is not useful. modemmanager instantly takes care of toggling the mode, so that when you plug in the modem, after a few seconds or maybe half a minute modemmanager has switched the modem to communications mode and NetworkManager is able to use it.

If you are using a Firmware before HF7 (or one of its Alpha/Beta versions) you have to install modemmanager. To do so, connect your Pandora to the Internet, open a terminal and, as a super user, intall it via opkg by entering the commands:

:sudo opkg update
:sudo opkg install modemmanager

'''Note:''' If you are using a firmware more recent than "Zaxxon" Hotfix 6 (starting with HF7) you do not have to follow the steps outlined above since modemmanager comes preinstalled.

'''Note 2:''' After plugging in the USB 3G modem, it may take some time until NetworkManager is able to use the modem. Wait for at least half a minute, until you give up and report that the modem doesn't work.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| ZTE K3565-Z / MF626 / MF627 / MF636
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__956513] [http://boards.openpandora.org/index.php?/topic/7226-superzaxxon-beta-11-released/page__pid__127881#entry127881]}}
| A how-to by shideneyu for this modem can be found [http://www.pandorawiki.org/ZTE_K3565Z_3G_USB_Modem here]
|-
|-
| BandLuxe C270
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| A how-to by relliker for this modem can be found [http://www.pandorawiki.org/BandLuxe_C270_3G_USB_Modem here]
|-
| Huawei E156G
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/52827-3gumts-usb-dongle/page__view__findpost__p__835681]}}
|
|-
| Huawei E160
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong. This one definitely needs modemmanager. After installing modemmanager, it works flawlessly.
|-
| Huawei E160E
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong.
|-
| Huawei E1750
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__939350]}}
|
|-
| [[wikipedia:Huawei E220|Huawei E220]]
| Not required
| Standard-A
| USB 1.1
| 500mA
| Standard-A port via High Speed hub
| {{No|Not on new kernels.}}
| The successful Pandora E220 tests were done by DJWillis on an old kernel (long before Pandora shipped). It seems that they are NOT working any more. Also tested on Linux (was it working?) This entry originally said 250mA, but there is no source and current sources say 500mA.
|-
| Huawei E3531
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Need recent USB_ModeSwitch compiled and installed, see (http://www.draisberghof.de/usb_modeswitch/); then type "usb_modeswitch -W -I -v 12d1 -p 15ca -M 55534243123456780000000000000011062000000101000100000000000000" to switch to modem mode (lsusb should change from 12d1:15ca to 12d1:1506). Enable automatic modem switch: sudo nano /etc/modutils/mobilestickserial and enter "usbserial vendor=0x12d1 product=0x15ca", sudo nano /etc/udev/rules.d/999-mobilestick.rules and enter "SUBSYSTEM=="usb", SYSFS{idProduct}=="15ca", SYSFS{idVendor}=="12d1", RUN+="/usr/sbin/usb_modeswitch -W -I -v 12d1 -p 15ca -M 55534243123456780000000000000011062000000101000100000000000000"", off course checking usb_modeswitch path, in this case /usr/sbin
|-
| 4G-Systems XS Stick P14
| Not required (usbserial module)
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__937681]}}
| Requires usbmodeswitch program.
|-
| iPhone 3GS (Probably also 1G/3G)
| ipheth
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Maybe|Should work in Angstrom with some work.}}
| Requires a good bit of dependencies to get working. Tested with Debian from SD, but should work in Angstrom with some work. The ipheth wwan0 device only provides a connection over the 3G modem, even if you're connected to a wifi network. I used the iproxy and SSH tunneling method with proxychains to get to the wifi network.
|-
| HTC Desire
| not required
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Yes}}
| Requires internet connection sharing to be enabled from the phone.
|-
| Samsung Galaxy Ace 2
| not required
| Micro-B female
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| Tested with phone firmware from T-Mobile (July 2012). Connect the USB cable, enable USB tethering on the phone, and connect to lfupdown on Pandora NetworkManager. Works with 3G and wifi.
|
|-
| Firefox Flame
| not required
| Standard-A -> Micro-B
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Tested with phone with software Boot2Gecko 3.0.0.0-prerelease. Connect the USB cable, enable USB tethering on the phone, and connect to ifupdown on Pandora NetworkManager. Works with 3G and Wi-Fi.
|}

== USB to Ethernet adapters ==

To enable USB Ethernet adapters on the Pandora, you may need to left-click the networking icon on the panel in Xfce, and select "Ifupdown (bnep0)".

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Mbps
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Apple USB Ethernet Adapter MB442Z/A
|
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Reportedly uses an ASIX AX88xxx chipset.
|-
| Apple USB Ethernet Adapter model A1277
|
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 05ac:1402 Apple, Inc.
|-
| ASUS USB Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0b95:7e2b ASIX Electronics Corp. AX88772B
|-
| Conrad 3-Port-USB-Hub und Netzwerk-Adapter
|
| Not required
| Standard-A
| USB 2.0
| A lot! {{HideableNotes|50% of battery charge only brings you 2h40min (min brightness, no other devices attached)}}
| Standard-A port
| {{Yes}}
| Has a 3port USB Hub included. External power supply can (and should) be attached, not included though. ASIX Chipset. 20€ @ [http://www.conrad.de/ce/de/product/976406/NOTEBOOK-MINI-DOCKINGSTATION-USBRJ45/SHOP_AREA_32315&promotionareaSearchDetail=005 Conrad Electronics]. Not tested in Linux.
|-
| Logitec USB 2.0 LAN-GTJ/U2B Ethernet adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) 1000Mbps=350mA 100Mbps=230mA 10Mbps=220mA(documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.logitec.co.jp/products/lan/langtju2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2B Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 100Mbps=170mA 10Mbps=210mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp.[http://www.logitec.co.jp/products/lan/lantxu2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 300mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp. USB hub current: 100mA (lsusb) 200mA (documentation). [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php] [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Wii USB 2.0 10/100M adapter (use [http://www.asix.com.tw/products.php?op=pItemdetail&PItemID=86;71;101 ASIX AX 88772 USB 2.0 chip])
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772. [http://www.dealextreme.com/details.dx/sku.5926 This clone from DealExtreme] works too.
|-
| Connectland USB 2.0 10/100M Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772 - Works fine, Sometimes a reboot is necessary (ZaxxonHF5RC1).
|-
| Belkin Gigabit USB 2.0 Network Adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| The shape of it make is a bit awkward to fit if you connect it directly, but it has a short adapter cable. I only get ~95Mbit on a gigabit network, but then the pandora's cpu maxes out. (it may be that the driver/usb stack isn't very well optimized), has horribly bright blue LEDs.
|-
| MosChip MCS7830 USB 10/100 Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Kernel module: mcs7830.
|-
| EU.MARK USB 10/100M RJ45 Ethernet Network Adapter Dongle
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| USB ID: 9710:7830 - bought from [http://www.dealextreme.com/details.dx/sku.22684 DealExtreme]
|-
| Digitus DN-10050 Fast Ethernet USB Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| MosChip MCS7830-based adapter. USB ID 9710:7830.
|-
| Edimax EU-4230 Fast Ethernet USB Adapter with 3-port USB hub [http://edimax.ie/images/Image/datasheet/USB/EU-4230/EU-4230_Datasheet.pdf]
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Ethernet USB ID 0b95:772a ASIX Electronics Corp. 3-port USB2.0 hub USB ID 0409:005a NEC Corp. Optional power adapter for USB hub.
|-
| Peabird USB v2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Consumes a lot of current. Fragile, the protective plastic cord cracked after one month. Hot. A blue light a bit too flashy. Definitely avoid this model.
|-
| SIIG JU-NE0012-S1 USB 2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16812191163 Newegg]
|-
| TRENDnet USB to Gigabit Ethernet Adapter TU2-ETG
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) Dormant: 5mA Static: 91mA Working: 131mA (documentation)
| Standard-A port
| {{Yes}}
| Rev. 2.0R ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.trendnet.com/products/proddetail.asp?prod=275_TU2-ETG&cat=42] Rev. 2.0R is white, previous versions are blue and consumes more current. The documentation's current draw are reported for 10 and 100Mbps.
|-
| Novatel Wireless Jetpack 4620L
|
| cdc_ether
| Standard-A
| USB
| High drain; 95% charge = 6:00 battery life.
| Standard-A port
| {{Yes}}
| This is a LTE/EVDO/CDMA/HSPA/UMTS/EDGE/GPRS Wifi Hotspot device; Device is registered as a USB Ethernet device when connected through USB tethered (as opposed to Wifi) connection. USB ID 1410:b008
|-
| LOGILINK UA0174A Fast Ethernet USB Adapter with 3-port USB hub
| 10/100
| Not required
| Standard-A
| USB 2.0
| about 300mA
| Standard-A port
| {{Yes}}
| This is a combined USB 2.0 3Port Hub and USB to Ethernet adapter. ID 0b95:772b ASIX Electronics Corp. AX88772C; bought at [http://www.reichelt.de/Netzwerkkarten/LOGILINK-UA0174A/3//index.html?ACTION=3&GROUPID=5822&ARTICLE=132333&SEARCH=usb%20ethernet&OFFSET=16&WKID=0&]
|}

== USB to serial adapters ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| pl203
| usbserial
| Standard-A
| USB 1.1
| 100mA. A powered hub is needed.
| Standard-A port
| {{Yes}}
| A powered hub is needed. Plug the device, then load USB modules. ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port.
|-
| SparkFun FTDI Basic Breakout
| not required
| Mini-B female
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| Tested the variant sold by eBay seller "goodlucksell".
|}

== USB WiFi adapters ==

The Pandora stock kernel may not come with all wireless driver support outside of the internal WiFi chip. Sometimes, the only way you'll get wireless working is to build your own kernel with it included or try [http://wireless.kernel.org/en/users/Download compat-wireless].

As for hofix 6a4 compat-wireless seems to be present in the kernel out of the box, so one can build a USB wireless driver for Pandora following this [http://boards.openpandora.org/index.php?/topic/5140-solvedbuilding-a-usb-wifi-driver/page__view__findpost__p__89280 algorithm]

As for [[hotfix 6]] Release Candidate the kernel includes drivers for these Realtek chips: RTL8712/8188/8191/8192SU/8192CU

See also [http://boards.openpandora.org/index.php?/topic/7160-micro-wifi-dongle/ this thread] on the forums for the latest.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| Advance Mini Wireless N150
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| There's a little hole on it, so it's useful for attaching it to the OP.
|-
| ASUS WL-167G v2
| rt73usb + rt2x00usb + rt2x00lib
| Standard-A
| USB 2.0
| 300mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 0b05:1723 ASUSTek Computer, Inc. WL-167G v2 802.11g Adapter [Ralink RT73]. Works pretty fine on Linux PC.
|-
| Belkin N1 Wireless USB Adapter (F5D8051) ("Ver. 2053") (MARVELL v1021)
| N/A
| Standard-A
| USB 2.0
| {{Unknown}}
| No connection was attempted.
| {{No|No native driver support and ndiswrapper obviously won't work.}}
| There's a previous revision of this dongle which is supposed to have a Ralink chip, but they revised it and put a different chip inside. Reported (by whom?) to work with ndiswrapper and works in Linux.
|-
| Belkin Surf micro
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Cisco/Linksys AE1000 High Performance Wireless-N USB Adapter
| rt3572sta (RT3572USB)
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A (Standard-A port?)
| {{Yes|Works with a modified driver.}}
| (Compiled module for pandora:[http://boards.openpandora.org/index.php?/topic/1992-linksys-ae1000-usb-wifi/ pandora forum]) Download the driver from [http://www.ralinktech.com/support.php?s=2 ralink's driver site], edit ./common/rtusb_dev_id.c, before "#endif // RT2870" add "{USB_DEVICE(0x13B1,0x002F)},", compile.' Reported (by whom?) to work in Linux.
|-
| D-Link WIRELESS G USB ADAPTER DWL-G122 rev.E1 F/W 5.00
| rt2870sta + rt2800usb + rt2800lib
| Standard-A
| USB 2.0
| 450mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 07d1:3c0f D-Link System AirPlus G DWL-G122 Wireless Adapter(rev.E) [Ralink RT2870]. Works pretty fine on Linux PC.
|-
| Digitus Wireless 150N USB 2.0 Adapter
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| Bundled with a non-WiFi Pandora coming from Craig's shop
|-
| Edimax EW-7811Un
| rtl8192cus
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Havit HV-WF15
| n/a
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since SuperZaxxon}}
|-
| Netgear WNA1000M
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Thomson WLG-1500A
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|Doesn't work.}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter
|-
| TRENDnet TEW-424UB V2
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|lsusb shows it, but no module is loaded}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter. Same behavior on a PC.
|-
| Alfa Network AWUS036H 1000mw
| RTL8187
| IEEE 802.11b/g
| USB 2.0
| ?
| USB A
| {{Yes|Yes}}
| can be found on ebay; tested with Beta 3
|-
| TP-Link 150Mbps Mini Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN723N. Tested with WPA2. Works out of the box. Cheap to buy (£6.99 from pcworld in the UK).
|-
| TP-Link 150Mbps '''Nano''' Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN725N. Works out of the box. From Reichelt.de. Claims to be RaspberryPi compatible on their website.
|-
| [http://www.tp-link.com.de/products/details/?model=TL-WN823N#spec TP-Link 300Mbps '''Mini''' Wireless N]
| Unknown
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN823N. Works out of the box. Is also RaspberryPi compatible. Has been tested.
|-
| TP-Link Atheros AR9170
| carl9170-1.fw
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{Yes|Yes}}
| Model No TL-WN821N. Works out of the box. ID 0cf3:1002
|-
|}

== DVB/TNT/TDT ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Module(s)
! Firmware
! Additional comments
|-
| AVerMedia AVerTV Volar Green HD
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| Should work
| af9033 tda18218
| dvb-usb-af9035-02.fw
| ID 07ca:a835 AVerMedia Technologies, Inc.
HD/PRO (A835)
|-
| AVerMedia AVerTV Volar Video Capture
| Standard-A
| USB 2.0
| Reported as 0mA. More likely to be 500mA
| Standard-A port
| ?
| ?
| ?
| ID 07ca:4830 AVerMedia Technologies, Inc.
H830
|-
| Hauppauge WinTV aero
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes|Yes}}
| smsmdtv
| sms1xxx-hcw-55xxx-dvbt-02.fw
| ID 2040:b900 Hauppauge . Also works on the mini-usb port.
|-
| Hauppauge WinTV-HVR 930C
| Standard-A
| USB 2.0
| 150mA (idle)
| Standard-A port
| {{No}}
| em28xx xc5000
| dvb-usb-hauppauge-hvr930c-drxk.fw dvb-fe-xc5000-1.6.114.fw
| ID 2040:1605 Hauppauge . Not able to get it to work yet. Embedded Remote control ID: 0525:a4aa
|-
| ITE 9135
| Standard-A
| USB 2.0
| 515mA
| Standard-A port
| {{Yes}}
| rtl2832 rtl2830
| dvb-usb-it9135-02.fw
| Gets very hot
|-
| MSI Digi Vox Min
| Standard-A
| USB 2.0
| ?
| Standard-A port
| {{Yes|Yes}}
| ?
| ?
| Realtek rtl2832u chipset
|-
| Realtek RTL2832U
| Standard-A
| USB 2.0
| 460mA
| Standard-A port
| {{Yes}}
| dbv_usb_af9035 dbv_usb_v2
| dvb-usb-it9135-02.fw
| idVendor=0bda, idProduct=2838
|-
| Realtek RTL2832UHIDIR
| Standard-A
| USB 2.0
| 464mA
| Standard-A port
| {{Yes}}
| dbv_usb_rtl28xxu
| dbv_usb_rtl28xxu.ko rtl2830.ko
| idVendor=0bda, idProduct=2838
|-
| Velleman Mini USB DBV-T receiver
| Standard-A
| USB 2.0
| 438mA
| Standard-A port
| {{Yes}}
| ?
| dvb-usb-it9135-01.fw
| remote control: rc-it913x-v2
|-
|}

= Storage =

== External Hard Disk Drives ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! style="min-width: 120px" | Works on Pandora
! Additional comments
|-
| Freecom 250GB 2.5" portable
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Inside it's a Samsung Model HM251JX. {{HideableNotes|So I guess anything based on that will also work OK.}}
|-
| (Intenso)® 2.5" MEMORYSTATION 1TB
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
|
|-
| LaCie Rikiki 250GB USB 2.0 2.5" Hard Drive
| Not required
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port via powered High Speed Hub
| {{Partial|Not when unpowered, needs testing with a powered hub}}
| Not only does it fail to spin up, but it causes the Pandora's screen to pulsate wildly, much like an old CRT would if you placed a speaker or a magnet near to it. Not tested with a powered hub.
|-
| Seagate Seagate® Expansion™ External Drives
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{No}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14781-hitnrun/ Hitnrun]. "Isn't even detected in lsusb (drive powered by external power source)"
|-
| Verbatim 250GB Model #47580 Hard Drive
| Not required
| Direct
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877512 almatuk]. {{HideableNotes|"Watched videos directly from it at full speed, no need for powered USB hub. Had issues playing roms directly off it however as it was formatted NTFS. I'm sure if I formatted to FAT32 these would disappear."}}
|-
| Western Digital 160GB Elements External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| standard-A port via powered High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB Elements Portable USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or standard-A port via High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB My Passport Essential USB 2.0 2.5" Hard Drive
| Not required
| {{Unknown|Direct?}}
| USB 2.0
| {{Unknown}}
| {{Unknown|Direct?}}
| {{Partial|Maybe}}
| Tested by TheDarkSpectrum48K. The first time it [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877386 "works perfectly!"]. The second time [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__882635 it didn't work].
|-
| Western Digital 400GB My Passport Essential USB 2.0 2.5" HDD model WDME4000TE
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14534-peca/ Peca].
|-
| Western Digital 500GB Elements Portable External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. {{HideableNotes|The USB cable that came with it was bad, so I used another one.[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949863]}}
|-
| Western Digital 500GB My Passport Essential External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works fine. {{HideableNotes|Came pre-formatted in NTFS, but should work if you downloaded the community codec pack. It said 1TB on the packaging, but there was 465GB free space, so I'm pretty sure it was actually the 500GB one.}}[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949645]
|-
| Western Digital 1TB My Passport Essential SE External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or through powered High Speed Hub
| {{Yes}}
| Tested by [http://http://www.gp32x.com/board/index.php?/user/19191-mycohl/ Mycohl]. {{HideableNotes|Externally powered hub recommended to conserve battery power.}}
|-
| Western Digital Elements 2TB 3.5" Hard Drive Model:WDBAAU0020HBK
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://boards.openpandora.org/index.php?/user/430-kilowatt/ kilowatt].
|}

== DVD/CD Drives ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Lite-On EZ-DUB DVD/CD Multi-Recorder (Model eZAU120)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter - DC 12V 1.8A
| Standard-A port
| {{No}}
| Works in Linux.
|-
| Memorex 20x Multi Format DVD Recorder External - DVD±RW (±R DL)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter
| Standard-A port
| {{Yes}}
|
|}

= Video display device =

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
| Tritton see2 usb 2.0 to SVGA adapter
| sisusb
| USB
| USB 2.0
| {{Unknown|High {{HideableNotes|Reduces Pandora's battery life in half (10h → 4h)}}}}
| VGA (D-SUB)
| {{Partial|Yes, but has performance issues.}}
| Needs to be integrated with preferences. {{HideableNotes|Currently I (who?) must edit xorg.conf and mess with xinerama.}} Good for presentations, dragging a window is bearable, but hi-res video is slow. Works in Linux without any issues.
|-
| DisplayLink usb 2.0 to SVGA adapter WS Tech USB-DVI
| udlfb
| USB
| USB 2.0
| 500mA
| VGA (D-SUB)
| Yes
| 17e9:0198 DisplayLink. No hub needed. Module and userspace here:
git clone http://git.plugable.com/webdav/udlfb/
git clone http://git.plugable.com/webdav/xf-video-udlfb/
|-
| Plugable DisplayLink UGA-165
| ?
| Mini-B female
| USB 2.0
| ?
| DVI/VGA/HDMI
| {{Yes}}
| In /etc/X11, copy xorg.conf.DisplayLink to xorg.conf then '''log out''' with the device attached [http://pandoralive.info/?p=3423]
Remark by [[User:Porg]] without having tested it myself. I guess quite ok for static content, but vivid/dynamic content may suffer lag, as the [https://plugable.com/products/uga-165/ | official product page] says:
"USB speed limitations prevent smooth playback with full-screen HD videos, and games suffer similar performance limitations or don't work at all since no direct hardware access (DirectX) is possible."
|-
| Magic Control Technology Corp. Trigger II External Graphics
| sisusb
| USB
| USB 2.0
| 500mA
| ?
| ?
| ID 0711:5200 Magic Control Technology Corp. A kernel recompile is needed. In /usr/src/linux/drivers/usb/misc/sisusbvga , edit sisusb.c , and add

{ USB_DEVICE(0x0711, 0x5200) },

in the list around line 3250
Get the latest xf86-video-sisusb driver here:
http://xorg.freedesk...ividual/driver/

|}

= Video capture devices =

== Webcams ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Exoo No Driver/USB 2.0 Webcam (Model No.: M053)
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| Bought from [http://www.dealextreme.com/details.dx/sku.14991 DealExtreme]. Works in Linux.
|-
| Logitech Quickcam Communicate Deluxe
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| USB ID: 046d:0992, works though [http://linux-uvc.berlios.de/ uvcvideo]. Works in Linux.
|-
| Logitech Webcam c210
| Not required
| Standard-A
| USB 2.0
| 170mA
| Standard-A port
| {{Yes}}
| ID 046d:0819 <unnamed>. Video and Audio recognized, tested to work.
|-
| Logitech HD Webcam C270 720p
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0825 Logitech, Inc. Audio recognized, but not tested. More info to come. Works in Linux.
|-
| Logitech HD Webcam Pro 9000
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0990 Logitech, Inc. Audio recognized, but not tested. Great Picture! Works in Linux.
|}

= Audio devices =

== Microphones/recorders ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.bluemic.com/yeti/] Blue Yeti
| not required
| standard-A
| unknown
| unknown
| standard-A port via High Speed USB hub
| {{unknown|Not thoroughly tested.}}
| Very roughly tested 2012-06-13 by [[user:spiralofhope|spiralofhope]] using Mumble. More testing required. {{HideableNotes|The system recognizes the Yeti, and it appears in Mumble's list of available devices, but the audio wizard doesn't show the Yeti as having input. Additional troubleshooting is required, as is checking the manual/company website for missing information.}}
|-
| [http://www.zoom.co.jp/english/products/h2/] Zoom H2 Handy Recorder
| not required
| standard-A
| USB 1.1
| 300mA
| standard-A port via High Speed USB hub
| {{Yes|Yes, needs a USB hub.}}
| Can record into Audacity, but won't be recognized unless connected through USB hub.[http://www.gp32x.com/board/index.php?/topic/59301-audacity-1-3-12/page__view__findpost__p__947602].
|}

== MIDI controllers ==

EvilDragon bundled the usb MIDI class drivers in the default firmware image, therefore ANY class-compliant MIDI device should work with the Pandora, out of the box.[http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Akai LKP25
| Not required
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]}}
|
|-
| M-Audio MIDISPORT 2x2 Anniv
| Not required
| {{Unknown}}
| {{Unknown}}
| 400mA
| {{Unknown}}
| {{Unknown}}
| ID 0763:1050 Midiman. High current draw!
|-
|}

== USB audio controllers ==

Some are "professional soundcard"; see [http://en.wikipedia.org/wiki/Sound_card#Professional_soundcards_.28audio_interfaces.29 definition on Wikipedia].

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Cakewalk UA-1G
| not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0582:00e9 Roland Corp. This device may be similar to older Edirol/Roland USB audio devices. Runs and record under Slackware. Jack audio server realtime recording works. Recognized but not tested under official OS. A hub, powered or not, is needed.
|-
| Connectland AUDIO ADAPTER
| not required
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes}}
| ID 0d8c:000c C-Media Electronics, Inc. Audio Adapter . CMedia CM108 Virtual 7.1 Channel Sound. Has vol +, vol -, mute headspeaker, mute mic buttons. Mini-jack audio in and out. A non-powered hub is needed.
|}

= Input devices =

Any HID ([http://en.wikipedia.org/wiki/Human_interface_device Human Interface Device]) compliant keyboard, mouse or game controller should work on the Pandora. Most of those device are low speed or full speed USB device and will need to be connected though either a [[USB_reference#OTG host mode|USB OTG adapter/cable]] or a [[USB reference#What’s all this stuff about USB 1.1 and USB 2.0? Isn’t USB, uh, universal?|USB2 hub]] in order to work on the Pandora.

== External Game Controllers ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| 2-TECH SNES-to-USB adapter
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| USB description is "HuiJia USB GamePad", <tt>lsusb</tt> calls it "0e8f:3013 GreenAsia Inc."
|-
| USB Super RetroPort (SNES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=29 RetroZone]. Works in Linux.
|-
| USB RetroPort (NES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=28 RetroZone]. Works in Linux.
|-
| Trio Linker Plus II (PlayStation,-GameCube,-and-Dreamcast-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Bought from [http://www.play-asia.com/paOS-13-71-6m-49-en-70-1zfv.html Play-Asia]. Works in Linux.
|-
| NAZAR V47 USB Force Feedback Vibrating Gamepad Controller for PC
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.24551 DealExtreme]. Works in Linux.
|-
| 10-Fire-Button Double Vibration Feedback USB PC Arcade Joystick
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.27821 DealExtreme]. Works in Linux.
|-
| Official PlayStation 3 controller
| Not required
| Standard-A
| Full speed
| {{Unknown}}
| USB A To Mini B Cable via High Speed Hub
| {{unknown}}
| This is for USB not bluetooth compatibility. Sixaxis and DualShock not tested. Works in Linux.
|-
| Saitek PLC Cyborg Force Rumble Pad (P2500) - 06a3:ff0c
| {{unknown}}
| Standard-A
| {{unknown}}
| 5V
| Standard-A port via High Speed Hub
| {{Unknown|Not fully tested}}
| Partial test attempted 2012-06-24 by [[user:spiralofhope|spiralofhope]]. lsusb lists it. More testing required. {{HideableNotes|A gamepad testing procedure needs to be defined. See [[Joystick testing]].}}
|-
| Thrustmaster Firestorm Digital 3 Gamepad
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| ID 07b5:0213 Mega World International, Ltd Thrustmaster Firestorm Digital 3 Gamepad.
|-
| Wired Xbox 360 Controller
| xpad module
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{unknown}}
| This also includes gamepads for PC that needs the Windows Xinput driver. Such gamepads include the Logitech Chillstream. Works in Linux.
|-
| WiseGroup.,Ltd SmartJoy Dual PLUS Adapter (dual PSX to USB joypad adapter)
| Not required
| Standard-A
| USB 1
| 100mA
| Standard-A port via USB 1-compatible High Speed Hub
| {{Yes}}
| ID 6677:8802. Works in Linux.
|-
| Logitech Cordless RumblePad 2
| Not required
| Standard-A
| Low speed
| 100mA
| Standard-A port via High Speed Hub
| {{Yes}}
| Product-ID: 0xc219, Vendor-ID: 0x046d (Logitech Inc.), [http://www.logitech.com/support/287 Official product support website], All buttons worked fine in PCSX, analog sticks not tested, but likely work"
|-
|}

== Touchpads ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.logitech.com/en-us/mice-pointers/mice/devices/8417 Logitech Wireless Touchpad]
| Not required
| Standard-A
| {{Unknown}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| Left and right four-finger swipes aren't mapped to anything by default in XFCE. They can be mapped as keyboard shortcuts.
|}

== Graphics tablets ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Works on Pandora
! Additional comments
|-
| Bamboo Multitouch
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__881806]}}
| It's not known if this works in Linux.
|-
| Genius Tablet
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes, [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__883140 via USB hub]}}
| It's not known if this works in Linux.
|-
| Wacom CTH-460
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__924422]}}
| Would need a patched driver to work. It's not known if this works in Linux.
|-
| Wacom Volito2 Tablet (Model: CTF-420)
| Not required
| Standard-A
| Low speed
| 40mA [http://www.my-volito.com/volito/specs.asp?lang=en]
| {{No}}
| USB ID: 056a:0062
|}

== Mice ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Works on Pandora
! Additional comments
|-
| Apple Mouse (M5769)
| USB
| {{No}}
| Seems to disable USB port, reboot afterwards required
|-
| Apple Mouse with Scroll Ball (A1152)
| USB
| {{Yes|Yes, needs a USB hub.}}
|
|-
| Cherry Ghostcord [http://www.amazon.de/Cherry-M85-26005DE-2-B-Unlimited-Home-Rechargeable/dp/B001EDSE0U/ref=tag_stp_s2_edpp_url]
| USB
| {{Yes|Yes, needs a USB hub.}}
| Part of a bundle with keyboard and a USB dongle for the connetion. With the dongle on the hub both devices work just fine (tested in XFCE)
|}

= Infrared =

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| TopSeed remote (branded ''Sapphire'' or ''CyberLink'')
| hid_topseed (added SZ 1.73)
| Standard-A
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| Some of the special buttons don't generate any key event.
|-
| Dangerous Prototypes IRToy
| cdc_acm (included)
| Mini-B female
| USB 1.1
| 200mA
| Standard-A port with hub
| {{Yes}}
| Can send and receive raw IR codes via the virtual serial connection. No application support yet.
|}

= Electronics development =
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Microchip PICkit 2
| not required
| Mini-B female
| USB 1.1
| <100mA
| OTG port
| {{Yes}}
| The pk2cmd application compiles easily.
|-
| Arduino Uno
| not required
| Standard-B female
| USB 1.1
| 50mA
| OTG port
| {{Yes}}
|
|-
| Arduino Leonardo
| not required
| Micro-B female
| USB 1.1
| 50mA
| Standard-A port with hub
| {{Yes}}
| The Arduino PND failes to compile sketches for the Leonardo, but a pre-programmed board can still communicate with the Pandora. The Leonardo makes an incorrect USB current request, but this can be reprogrammed if you want to use it on the OTG port - in Arduino's ''USBCore.h'', change ''USB_CONFIG_POWER_MA(500)'' to 100.
|}

= Connectors, adapters, and hubs =

This section is intended as a general guide. Items in this section are standard USB accessories, so drivers are not required. Compatibility with Pandora is assumed. Please note that any external product links are provided for reference only, and are not an endorsement.

== OTG (On The Go) Adapters ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Generic adapter
| {{No}}
| [http://shop.ebay.com/?_from=R40&_trksid=p3907.m38.l1313&_nkw=usb+otg+host+cable&_sacat=See-All-Categories Find on eBay] [http://www.amazon.co.uk/s/ref=nb_ss_ce?url=search-alias%3Delectronics&field-keywords=OTG+Cable+Adapter&x=3&y=23 Find on Amazon] These links are not 100% accurate. Check for `mini-a`, and on eBay, the price is higher by about $8.
|-
|Hama 00074214
| {{Yes}}
|[http://www.hama.de/00074214/hama-mini-usb-adapter-mini-usb-a-plug-usb-a-socket-015-m Manufacturer Page]
|-
| Nokia USB OTG adapter
| {{Yes}}
| [http://www.electronicproductonline.com/catalog/product_info.php?cPath=35_67&products_id=2043 Electronic Product Online]
|}

== Compact USB Hubs ==

Be sure to enable USB-host!

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Griffin SmartShare USB [http://www.griffintechnology.com/products/smartshare-usb]
| {{No}}
|
|-
| Belkin F5U415 4 Port USB 2.0 Swivel Hub [http://catalog.belkin.com/IWCatProductPage.process?Product_Id=377085]
| {{No}}
| Comes with an optional power adapter.
|-
| Belkin F5U700 USB 2.0 7-Port Lighted Hub [http://www.belkin.com/uk/support/article/?lid=enu&pid=F5U700ea&aid=10289&scid=947]
| {{Yes}}
| Tested 2012-06-16 by [[user:spiralofhope|spiralofhope]] both with and without its power adapter.
|-
| Belkin F5U701 USB 2.0 7 Port Mobile Hub [http://www.belkin.com/IWCatProductPage.process?Product_Id=369788]
| {{Yes}}
| Tested by pabloh. Comes with an optional power adapter.
|-
| ID 0e8f:0016 GreenAsia Inc.
| {{No}}
| Tested by tsh. Labeled as high speed. Bought from ebay.
|-
| ID 05e3:0608 Targus with Genesys Logic 4 Port USB 2.0 Hub
| {{Yes}}
| Tested by Kazuki. Works.
|-
|Trust 4 port netbook hub ID 05e3:0608
| {{Yes}}
| Tested by tsh. Bought from [http://www.amazon.co.uk/gp/product/B0025X16AS Amazon].
|-
| High Speed 4 Port Mini USB 2.0 Hub for Laptop PC (non powered)
| {{Yes}}
| Octopus-style small cheap unpowered USB hub. Bought from [http://cgi.benl.ebay.be/ws/eBayISAPI.dll?ViewItem&item=270538502843 ebay]
|-
| Keeptech USB 2.0 Hub (7 Ports) with Power Adapter, KT-UH703 [http://www.keeptech.com/books_show.php?id=144]
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works powered or unpowered.
|-
| Logitech Premium 4-Port USB Hub [http://www.logitech.com/en-in/notebook-products/usb-hubs/devices/3048]
| {{Yes}}
|
|-
| LUPO 7-port USB 2.0 Hub (cheap octopus type which can be powered as there is dc socket)
| {{Partial|Yes. {{HideableNotes|Can use a power supply but wasn't tested with one.}}}}
| Tested by kilowatt. Bought from [http://www.amazon.co.uk/gp/product/B003BVDABG/ref=oss_product from amazon uk]
|-
| LogiLink USB 2.0 Hub 4-Port UA0086 [http://www.logilink.eu/showproduct/UA0086.htm]
| {{Yes}}
| Tested by Jones. Comes with an optional power adapter.
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php]
| {{Yes}}
| See [http://pandorawiki.org/USB_compatibility_list#USB_to_Ethernet_adapters USB to ethernet adapters] for more details. USB 1 devices work perfectly. Also available as other brands: [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Rosewill RHB-220 4-port USB 2.0 Hub
| {{Yes}}
| Tested by Tyrant1919. Unpowered. Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16817182168 Newegg].
|-
| i-rocks SLEEK HUB USB 2.0 4 Ports Hub [http://www.i-rocks.com/Product_detail.aspx?CLASS_ID=1036&PRODUCT_ID=1080]
| {{Yes}}
| Comes with an ac adapter, but can be used without. USB 1 devices work perfectly.
|-
| MSI StarHub201
| {{Yes}}
| Testet by mclien with keyboard and mouse in XFCE, unpowered, not on the MSI site (discontinnued, guess) [http://alatest.dk/anmeldelser/hubs-og-switches/msi-star-hub-201/po3-34222999,42/]
|}

[[Category:USB]]
[[Category:List]]

PND management workflow

2013-10-24T13:15:13Z

Porg: /* Outcome of this UX guideline */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, Hotkey / text-based launchers
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).
Potentially also the parental folders have a meta meaning for their contained PNDs (most likely: Genre aka sub/category).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

== Outcome of this UX guideline ==

This document and the accompanying discussions, such as [http://boards.openpandora.org/index.php/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ Usability of package management (PND)] et al, served as a matter of discourse, which to some degree inspired package managers such as [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager] and launchers like [[Minimenu]] , [http://repo.openpandora.org/?page=detail&app=package.pandafe Pandafe] or [http://boards.openpandora.org/index.php/topic/12745-the-tournament-hub-launcher/ The Tournament Hub].

[[Category:Ideas and proposals]]

PND management workflow

2013-10-24T13:14:14Z

Porg: inserted forum thread as link (ref currently not working)

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, Hotkey / text-based launchers
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).
Potentially also the parental folders have a meta meaning for their contained PNDs (most likely: Genre aka sub/category).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

== Outcome of this UX guideline ==

This document and the accompanying forum discussions, such as [http://boards.openpandora.org/index.php/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ Usability of package management (PND)], served as a matter of discourse, which to some degree inspired package managers such as [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager] and launchers like [[Minimenu]] , [http://repo.openpandora.org/?page=detail&app=package.pandafe Pandafe] or [http://boards.openpandora.org/index.php/topic/12745-the-tournament-hub-launcher/ The Tournament Hub].

[[Category:Ideas and proposals]]

PND management workflow

2013-10-24T11:13:31Z

Porg: /* Outcome of this UX guideline */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, Hotkey / text-based launchers
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).
Potentially also the parental folders have a meta meaning for their contained PNDs (most likely: Genre aka sub/category).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

== Outcome of this UX guideline ==

This document served as a matter of discourse, which to some degree inspired package managers such as [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager] and launchers such as [[Minimenu]] , [http://repo.openpandora.org/?page=detail&app=package.pandafe Pandafe] or [http://boards.openpandora.org/index.php/topic/12745-the-tournament-hub-launcher/ The Tournament Hub].

[[Category:Ideas and proposals]]

Compo4All

2013-07-20T19:44:59Z

Porg: /* Launchers */ Added Compo4All Manager URL as meanwhile released

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

== 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])

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

== Developers SDK ==
Details of the API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]]

Compo4All

2013-06-29T20:31:19Z

Porg: /* Launchers */ Added Tournament Hub URL as meanwhile released

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

== 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 Profile Manager (Not yet available)
* [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])

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

== Developers SDK ==
Details of the API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]]

Compo4All

2013-05-15T11:07:58Z

Porg:

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

== 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 Profile Manager (Not yet available)
* [http://pandorawiki.org/User:Pmprog pmprog's] Tournament Hub (Not yet available) ([http://boards.openpandora.org/index.php/topic/12745-pandora-compo4all-ui/ Forum Thread])

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

== Developers SDK ==
Details of the API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]]

Compo4All

2013-05-15T11:07:31Z

Porg: First paragraphs need no section, but rather just open article. Changed "indie games" to "PND games".

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

== 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 Profile Manager (Not yet available)
* [http://pandorawiki.org/User:Pmprog pmprog's] Tournament Hub (Not yet available) ([http://boards.openpandora.org/index.php/topic/12745-pandora-compo4all-ui/ Forum Thread])

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

== Developers SDK ==
Details of the API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]]

Compo4All

2013-05-15T11:01:59Z

Porg: /* Scoreboard */ Written the URL explicitly, so that people will memorize it.

= Compo4All =
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 a few indie games.

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

== 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 Profile Manager (Not yet available)
* [http://pandorawiki.org/User:Pmprog pmprog's] Tournament Hub (Not yet available) ([http://boards.openpandora.org/index.php/topic/12745-pandora-compo4all-ui/ Forum Thread])

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

== Developers SDK ==
Details of the API for integrating with the Compo4All system can be found [[Compo4AllSDK|here]]

PND management workflow

2013-04-27T21:31:25Z

Porg: /* Overview */

USB compatibility list

2013-04-21T18:35:46Z

Porg: /* External Game Controllers */ Logitech Cordless RumblePad 2

This is a list of USB devices that have been tested on the Pandora. If the device you want to know about isn't listed here, don't worry! Just go to [[USB_reference|the USB reference page]], look up the specs of your device, and you may be able to figure out if it's compatible.

= Troubleshooting =

Each type of device will have its own unique way to troubleshoot.

But here are some general tips:

* Is USB-Host enabled?
* check <tt>lsusb</tt>
* check <tt>dmesg</tt>

When asking for help on [http://boards.openpandora.org/index.php?/forum/8-support/ the forums support board], be sure to post both your <tt>lsusb</tt> and <tt>dmesg</tt>.

Because <tt>dmesg</tt> output is very long, you need to paste it within [spoiler] tags like this:

[spoiler]
(paste your dmesg in here)
[/spoiler]

An easy way to get your <tt>dmesg</tt> so you can easily copy and paste it, is:

dmesg|leafpad

<tt>leafpad</tt> will open with the output of <tt>dmesg</tt>.

If you have no networking on your palmtop, you can send the information to a text file like this:

cd (your storage card)
dmesg>textfile.txt
sync

Then you can remove your card (if no programs are using it or PNDs are running on it) and bring it to a card reader on your desktop.

= Networking =

Please see the [[Mobile broadband]] page for tips on how to get these working, as well as [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/ this tutorial] from the GP32X forum.

== HSDPA (3G) Modems ==

Please note that many (if not all) USB 3G modems need modemmanager to be installed for switching from mass storage mode to serial communications mode. When first plugged in, most 3G USB modems claim to be a mass storage device and offer, on its built-in flash, drivers and connectivity software to be installed. Mostly this is only for Windows and Mac, so for the Pandora this is not useful. modemmanager instantly takes care of toggling the mode, so that when you plug in the modem, after a few seconds or maybe half a minute modemmanager has switched the modem to communications mode and NetworkManager is able to use it.

If you are using a Firmware before HF7 (or one of its Alpha/Beta versions) you have to install modemmanager. To do so, connect your Pandora to the Internet, open a terminal and, as a super user, intall it via opkg by entering the commands:

:sudo opkg update
:sudo opkg install modemmanager

'''Note:''' If you are using a firmware more recent than "Zaxxon" Hotfix 6 (starting with HF7) you do not have to follow the steps outlined above since modemmanager comes preinstalled.

'''Note 2:''' After plugging in the USB 3G modem, it may take some time until NetworkManager is able to use the modem. Wait for at least half a minute, until you give up and report that the modem doesn't work.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| ZTE K3565-Z / MF626 / MF627 / MF636
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__956513] [http://boards.openpandora.org/index.php?/topic/7226-superzaxxon-beta-11-released/page__pid__127881#entry127881]}}
| A how-to by shideneyu for this modem can be found [http://www.pandorawiki.org/ZTE_K3565Z_3G_USB_Modem here]
|-
|-
| BandLuxe C270
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| A how-to by relliker for this modem can be found [http://www.pandorawiki.org/BandLuxe_C270_3G_USB_Modem here]
|-
| Huawei E156G
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/52827-3gumts-usb-dongle/page__view__findpost__p__835681]}}
|
|-
| Huawei E160
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong. This one definitely needs modemmanager. After installing modemmanager, it works flawlessly.
|-
| Huawei E160E
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong.
|-
| Huawei E1750
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__939350]}}
|
|-
| [[wikipedia:Huawei E220|Huawei E220]]
| Not required
| Standard-A
| USB 1.1
| 500mA
| Standard-A port via High Speed hub
| {{No|Not on new kernels.}}
| The successful Pandora E220 tests were done by DJWillis on an old kernel (long before Pandora shipped). It seems that they are NOT working any more. Also tested on Linux (was it working?) This entry originally said 250mA, but there is no source and current sources say 500mA.
|-
| 4G-Systems XS Stick P14
| Not required (usbserial module)
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__937681]}}
| Requires usbmodeswitch program.
|-
| iPhone 3GS (Probably also 1G/3G)
| ipheth
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Maybe|Should work in Angstrom with some work.}}
| Requires a good bit of dependencies to get working. Tested with Debian from SD, but should work in Angstrom with some work. The ipheth wwan0 device only provides a connection over the 3G modem, even if you're connected to a wifi network. I used the iproxy and SSH tunneling method with proxychains to get to the wifi network.
|-
| HTC Desire
| not required
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Yes}}
| Requires internet connection sharing to be enabled from the phone.
|}

== USB to Ethernet adapters ==

To enable USB Ethernet adapters on the Pandora, you may need to left-click the networking icon on the panel in Xfce, and select "Ifupdown (bnep0)".

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Mbps
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Apple USB Ethernet Adapter MB442Z/A
|
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Reportedly uses an ASIX AX88xxx chipset.
|-
| Apple USB Ethernet Adapter model A1277
|
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 05ac:1402 Apple, Inc.
|-
| ASUS USB Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0b95:7e2b ASIX Electronics Corp. AX88772B
|-
| Conrad 3-Port-USB-Hub und Netzwerk-Adapter
|
| Not required
| Standard-A
| USB 2.0
| A lot! {{HideableNotes|50% of battery charge only brings you 2h40min (min brightness, no other devices attached)}}
| Standard-A port
| {{Yes}}
| Has a 3port USB Hub included. External power supply can (and should) be attached, not included though. ASIX Chipset. 20€ @ [http://www.conrad.de/ce/de/product/976406/NOTEBOOK-MINI-DOCKINGSTATION-USBRJ45/SHOP_AREA_32315&promotionareaSearchDetail=005 Conrad Electronics]. Not tested in Linux.
|-
| Logitec USB 2.0 LAN-GTJ/U2B Ethernet adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) 1000Mbps=350mA 100Mbps=230mA 10Mbps=220mA(documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.logitec.co.jp/products/lan/langtju2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2B Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 100Mbps=170mA 10Mbps=210mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp.[http://www.logitec.co.jp/products/lan/lantxu2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 300mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp. USB hub current: 100mA (lsusb) 200mA (documentation). [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php] [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Wii USB 2.0 10/100M adapter (use [http://www.asix.com.tw/products.php?op=pItemdetail&PItemID=86;71;101 ASIX AX 88772 USB 2.0 chip])
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772. [http://www.dealextreme.com/details.dx/sku.5926 This clone from DealExtreme] works too.
|-
| Connectland USB 2.0 10/100M Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772 - Works fine, Sometimes a reboot is necessary (ZaxxonHF5RC1).
|-
| Belkin Gigabit USB 2.0 Network Adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| The shape of it make is a bit awkward to fit if you connect it directly, but it has a short adapter cable. I only get ~95Mbit on a gigabit network, but then the pandora's cpu maxes out. (it may be that the driver/usb stack isn't very well optimized), has horribly bright blue LEDs.
|-
| MosChip MCS7830 USB 10/100 Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Kernel module: mcs7830.
|-
| EU.MARK USB 10/100M RJ45 Ethernet Network Adapter Dongle
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| USB ID: 9710:7830 - bought from [http://www.dealextreme.com/details.dx/sku.22684 DealExtreme]
|-
| Digitus DN-10050 Fast Ethernet USB Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| MosChip MCS7830-based adapter. USB ID 9710:7830.
|-
| Edimax EU-4230 Fast Ethernet USB Adapter with 3-port USB hub [http://edimax.ie/images/Image/datasheet/USB/EU-4230/EU-4230_Datasheet.pdf]
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Ethernet USB ID 0b95:772a ASIX Electronics Corp. 3-port USB2.0 hub USB ID 0409:005a NEC Corp. Optional power adapter for USB hub.
|-
| Peabird USB v2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Consumes a lot of current. Fragile, the protective plastic cord cracked after one month. Hot. A blue light a bit too flashy. Definitely avoid this model.
|-
| SIIG JU-NE0012-S1 USB 2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16812191163 Newegg]
|-
| TRENDnet USB to Gigabit Ethernet Adapter TU2-ETG
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) Dormant: 5mA Static: 91mA Working: 131mA (documentation)
| Standard-A port
| {{Yes}}
| Rev. 2.0R ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.trendnet.com/products/proddetail.asp?prod=275_TU2-ETG&cat=42] Rev. 2.0R is white, previous versions are blue and consumes more current. The documentation's current draw are reported for 10 and 100Mbps.
|-
| Novatel Wireless Jetpack 4620L
|
| cdc_ether
| Standard-A
| USB
| High drain; 95% charge = 6:00 battery life.
| Standard-A port
| {{Yes}}
| This is a LTE/EVDO/CDMA/HSPA/UMTS/EDGE/GPRS Wifi Hotspot device; Device is registered as a USB Ethernet device when connected through USB tethered (as opposed to Wifi) connection. USB ID 1410:b008
|}

== USB to serial adapters ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| pl203
| usbserial
| Standard-A
| USB 1.1
| 100mA. A powered hub is needed.
| Standard-A port
| {{Yes}}
| A powered hub is needed. Plug the device, then load USB modules. ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port.
|}

== USB WiFi adapters ==

The Pandora stock kernel may not come with all wireless driver support outside of the internal WiFi chip. Sometimes, the only way you'll get wireless working is to build your own kernel with it included or try [http://wireless.kernel.org/en/users/Download compat-wireless].

As for hofix 6a4 compat-wireless seems to be present in the kernel out of the box, so one can build a USB wireless driver for Pandora following this [http://boards.openpandora.org/index.php?/topic/5140-solvedbuilding-a-usb-wifi-driver/page__view__findpost__p__89280 algorithm]

As for [[hotfix 6]] Release Candidate the kernel includes drivers for these Realtek chips: RTL8712/8188/8191/8192SU/8192CU

See also [http://boards.openpandora.org/index.php?/topic/7160-micro-wifi-dongle/ this thread] on the forums for the latest.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| Advance Mini Wireless N150
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| There's a little hole on it, so it's useful for attaching it to the OP.
|-
| ASUS WL-167G v2
| rt73usb + rt2x00usb + rt2x00lib
| Standard-A
| USB 2.0
| 300mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 0b05:1723 ASUSTek Computer, Inc. WL-167G v2 802.11g Adapter [Ralink RT73]. Works pretty fine on Linux PC.
|-
| Belkin N1 Wireless USB Adapter (F5D8051) ("Ver. 2053") (MARVELL v1021)
| N/A
| Standard-A
| USB 2.0
| {{Unknown}}
| No connection was attempted.
| {{No|No native driver support and ndiswrapper obviously won't work.}}
| There's a previous revision of this dongle which is supposed to have a Ralink chip, but they revised it and put a different chip inside. Reported (by whom?) to work with ndiswrapper and works in Linux.
|-
| Belkin Surf micro
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Cisco/Linksys AE1000 High Performance Wireless-N USB Adapter
| rt3572sta (RT3572USB)
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A (Standard-A port?)
| {{Yes|Works with a modified driver.}}
| (Compiled module for pandora:[http://boards.openpandora.org/index.php?/topic/1992-linksys-ae1000-usb-wifi/ pandora forum]) Download the driver from [http://www.ralinktech.com/support.php?s=2 ralink's driver site], edit ./common/rtusb_dev_id.c, before "#endif // RT2870" add "{USB_DEVICE(0x13B1,0x002F)},", compile.' Reported (by whom?) to work in Linux.
|-
| D-Link WIRELESS G USB ADAPTER DWL-G122 rev.E1 F/W 5.00
| rt2870sta + rt2800usb + rt2800lib
| Standard-A
| USB 2.0
| 450mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 07d1:3c0f D-Link System AirPlus G DWL-G122 Wireless Adapter(rev.E) [Ralink RT2870]. Works pretty fine on Linux PC.
|-
| Digitus Wireless 150N USB 2.0 Adapter
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| Bundled with a non-WiFi Pandora coming from Craig's shop
|-
| Edimax EW-7811Un
| rtl8192cus
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Netgear WNA1000M
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Thomson WLG-1500A
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|Doesn't work.}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter
|-
| TRENDnet TEW-424UB V2
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|lsusb shows it, but no module is loaded}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter. Same behavior on a PC.
|-
| Alfa Network AWUS036H 1000mw
| RTL8187
| IEEE 802.11b/g
| USB 2.0
| ?
| USB A
| {{Yes|Yes}}
| can be found on ebay; tested with Beta 3
|-
| TP-Link 150Mbps Mini Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN723N. Tested with WPA2. Works out of the box. Cheap to buy (£6.99 from pcworld in the UK).
|-
|}

== DVB/TNT/TDT ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Module(s)
! Firmware
! Additional comments
|-
| AVerMedia AVerTV Volar Green HD
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| Should work
| af9033 tda18218
| dvb-usb-af9035-02.fw
| ID 07ca:a835 AVerMedia Technologies, Inc.
HD/PRO (A835)
|-
| AVerMedia AVerTV Volar Video Capture
| Standard-A
| USB 2.0
| Reported as 0mA. More likely to be 500mA
| Standard-A port
| ?
| ?
| ?
| ID 07ca:4830 AVerMedia Technologies, Inc.
H830
|-
| Hauppauge WinTV aero
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes|Yes}}
| smsmdtv
| sms1xxx-hcw-55xxx-dvbt-02.fw
| ID 2040:b900 Hauppauge . Also works on the mini-usb port.
|-
| MSI Digi Vox Min
| Standard-A
| USB 2.0
| ?
| Standard-A port
| {{Yes|Yes}}
| ?
| ?
| Realtek rtl2832u chipset
|-
|}

= Storage =

== External Hard Disk Drives ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! style="min-width: 120px" | Works on Pandora
! Additional comments
|-
| Freecom 250GB 2.5" portable
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Inside it's a Samsung Model HM251JX. {{HideableNotes|So I guess anything based on that will also work OK.}}
|-
| (Intenso)® 2.5" MEMORYSTATION 1TB
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
|
|-
| LaCie Rikiki 250GB USB 2.0 2.5" Hard Drive
| Not required
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port via powered High Speed Hub
| {{Partial|Not when unpowered, needs testing with a powered hub}}
| Not only does it fail to spin up, but it causes the Pandora's screen to pulsate wildly, much like an old CRT would if you placed a speaker or a magnet near to it. Not tested with a powered hub.
|-
| Seagate Seagate® Expansion™ External Drives
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{No}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14781-hitnrun/ Hitnrun]. "Isn't even detected in lsusb (drive powered by external power source)"
|-
| Verbatim 250GB Model #47580 Hard Drive
| Not required
| Direct
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877512 almatuk]. {{HideableNotes|"Watched videos directly from it at full speed, no need for powered USB hub. Had issues playing roms directly off it however as it was formatted NTFS. I'm sure if I formatted to FAT32 these would disappear."}}
|-
| Western Digital 160GB Elements External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| standard-A port via powered High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB Elements Portable USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or standard-A port via High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB My Passport Essential USB 2.0 2.5" Hard Drive
| Not required
| {{Unknown|Direct?}}
| USB 2.0
| {{Unknown}}
| {{Unknown|Direct?}}
| {{Partial|Maybe}}
| Tested by TheDarkSpectrum48K. The first time it [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877386 "works perfectly!"]. The second time [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__882635 it didn't work].
|-
| Western Digital 400GB My Passport Essential USB 2.0 2.5" HDD model WDME4000TE
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14534-peca/ Peca].
|-
| Western Digital 500GB Elements Portable External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. {{HideableNotes|The USB cable that came with it was bad, so I used another one.[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949863]}}
|-
| Western Digital 500GB My Passport Essential External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works fine. {{HideableNotes|Came pre-formatted in NTFS, but should work if you downloaded the community codec pack. It said 1TB on the packaging, but there was 465GB free space, so I'm pretty sure it was actually the 500GB one.}}[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949645]
|-
| Western Digital 1TB My Passport Essential SE External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or through powered High Speed Hub
| {{Yes}}
| Tested by [http://http://www.gp32x.com/board/index.php?/user/19191-mycohl/ Mycohl]. {{HideableNotes|Externally powered hub recommended to conserve battery power.}}
|-
| Western Digital Elements 2TB 3.5" Hard Drive Model:WDBAAU0020HBK
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://boards.openpandora.org/index.php?/user/430-kilowatt/ kilowatt].
|}

== DVD/CD Drives ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Lite-On EZ-DUB DVD/CD Multi-Recorder (Model eZAU120)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter - DC 12V 1.8A
| Standard-A port
| {{No}}
| Works in Linux.
|-
| Memorex 20x Multi Format DVD Recorder External - DVD±RW (±R DL)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter
| Standard-A port
| {{Yes}}
|
|}

= Video display device =

== VGA DVI HDMI adapter ==

No devices have been tested yet

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
|
|
|
|
|
|
|
| No devices have been tested yet
|}

==== External graphics cards ====

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
| Tritton see2 usb 2.0 to SVGA adapter
| sisusb
| USB
| USB 2.0
| {{Unknown|High {{HideableNotes|Reduces Pandora's battery life in half (10h → 4h)}}}}
| VGA (D-SUB)
| {{Partial|Yes, but has performance issues.}}
| Needs to be integrated with preferences. {{HideableNotes|Currently I (who?) must edit xorg.conf and mess with xinerama.}} Good for presentations, dragging a window is bearable, but hi-res video is slow. Works in Linux without any issues.
|-
| DisplayLink usb 2.0 to SVGA adapter WS Tech USB-DVI
| udlfb
| USB
| USB 2.0
| 500mA
| VGA (D-SUB)
| Yes
| 17e9:0198 DisplayLink. No hub needed. Module and userspace here:
git clone http://git.plugable.com/webdav/udlfb/
git clone http://git.plugable.com/webdav/xf-video-udlfb/
|-
| Magic Control Technology Corp. Trigger II External Graphics
| sisusb
| USB
| USB 2.0
| 500mA
| ?
| ?
| ID 0711:5200 Magic Control Technology Corp. A kernel recompile is needed. In /usr/src/linux/drivers/usb/misc/sisusbvga , edit sisusb.c , and add

{ USB_DEVICE(0x0711, 0x5200) },

in the list around line 3250
Get the latest xf86-video-sisusb driver here:
http://xorg.freedesk...ividual/driver/

|}

= Video capture devices =

== Webcams ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Exoo No Driver/USB 2.0 Webcam (Model No.: M053)
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| Bought from [http://www.dealextreme.com/details.dx/sku.14991 DealExtreme]. Works in Linux.
|-
| Logitech Quickcam Communicate Deluxe
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| USB ID: 046d:0992, works though [http://linux-uvc.berlios.de/ uvcvideo]. Works in Linux.
|-
| Logitech HD Webcam C270 720p
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0825 Logitech, Inc. Audio recognized, but not tested. More info to come. Works in Linux.
|-
| Logitech HD Webcam Pro 9000
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0990 Logitech, Inc. Audio recognized, but not tested. Great Picture! Works in Linux.
|}

= Audio devices =

== Microphones/recorders ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.bluemic.com/yeti/] Blue Yeti
| not required
| standard-A
| unknown
| unknown
| standard-A port via High Speed USB hub
| {{unknown|Not thoroughly tested.}}
| Very roughly tested 2012-06-13 by [[user:spiralofhope|spiralofhope]] using Mumble. More testing required. {{HideableNotes|The system recognizes the Yeti, and it appears in Mumble's list of available devices, but the audio wizard doesn't show the Yeti as having input. Additional troubleshooting is required, as is checking the manual/company website for missing information.}}
|-
| [http://www.zoom.co.jp/english/products/h2/] Zoom H2 Handy Recorder
| not required
| standard-A
| USB 1.1
| 300mA
| standard-A port via High Speed USB hub
| {{Yes|Yes, needs a USB hub.}}
| Can record into Audacity, but won't be recognized unless connected through USB hub.[http://www.gp32x.com/board/index.php?/topic/59301-audacity-1-3-12/page__view__findpost__p__947602].
|}

== MIDI controllers ==

EvilDragon bundled the usb MIDI class drivers in the default firmware image, therefore ANY class-compliant MIDI device should work with the Pandora, out of the box.[http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Akai LKP25
| Not required
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]}}
|
|-
| M-Audio MIDISPORT 2x2 Anniv
| Not required
| {{Unknown}}
| {{Unknown}}
| 400mA
| {{Unknown}}
| {{Unknown}}
| ID 0763:1050 Midiman. High current draw!
|-
|}

== USB audio controllers ==

Some are "professional soundcard"; see [http://en.wikipedia.org/wiki/Sound_card#Professional_soundcards_.28audio_interfaces.29 definition on Wikipedia].

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Cakewalk UA-1G
| not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0582:00e9 Roland Corp. This device may be similar to older Edirol/Roland USB audio devices. Runs and record under Slackware. Jack audio server realtime recording works. Recognized but not tested under official OS. A hub, powered or not, is needed.
|-
| Connectland AUDIO ADAPTER
| not required
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes}}
| ID 0d8c:000c C-Media Electronics, Inc. Audio Adapter . CMedia CM108 Virtual 7.1 Channel Sound. Has vol +, vol -, mute headspeaker, mute mic buttons. Mini-jack audio in and out. A non-powered hub is needed.
|}

= Input devices =

Any HID ([http://en.wikipedia.org/wiki/Human_interface_device Human Interface Device]) compliant keyboard, mouse or game controller should work on the Pandora. Most of those device are low speed or full speed USB device and will need to be connected though either a [[USB_reference#OTG host mode|USB OTG adapter/cable]] or a [[USB reference#What’s all this stuff about USB 1.1 and USB 2.0? Isn’t USB, uh, universal?|USB2 hub]] in order to work on the Pandora.

== External Game Controllers ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| 2-TECH SNES-to-USB adapter
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| USB description is "HuiJia USB GamePad", <tt>lsusb</tt> calls it "0e8f:3013 GreenAsia Inc."
|-
| USB Super RetroPort (SNES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=29 RetroZone]. Works in Linux.
|-
| USB RetroPort (NES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=28 RetroZone]. Works in Linux.
|-
| Trio Linker Plus II (PlayStation,-GameCube,-and-Dreamcast-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.play-asia.com/paOS-13-71-6m-49-en-70-1zfv.html Play-Asia]. Works in Linux.
|-
| NAZAR V47 USB Force Feedback Vibrating Gamepad Controller for PC
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.24551 DealExtreme]. Works in Linux.
|-
| 10-Fire-Button Double Vibration Feedback USB PC Arcade Joystick
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.27821 DealExtreme]. Works in Linux.
|-
| Official PlayStation 3 controller
| Not required
| Standard-A
| Full speed
| {{Unknown}}
| USB A To Mini B Cable via High Speed Hub
| {{No}}
| This is for USB not bluetooth compatibility. Sixaxis and DualShock not tested. Works in Linux.
|-
| Saitek PLC Cyborg Force Rumble Pad (P2500) - 06a3:ff0c
| {{unknown}}
| Standard-A
| {{unknown}}
| 5V
| Standard-A port via High Speed Hub
| {{Unknown|Not fully tested}}
| Partial test attempted 2012-06-24 by [[user:spiralofhope|spiralofhope]]. lsusb lists it. More testing required. {{HideableNotes|A gamepad testing procedure needs to be defined. See [[Joystick testing]].}}
|-
| Thrustmaster Firestorm Digital 3 Gamepad
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| ID 07b5:0213 Mega World International, Ltd Thrustmaster Firestorm Digital 3 Gamepad.
|-
| Wired Xbox 360 Controller
| xpad module
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| This also includes gamepads for PC that needs the Windows Xinput driver. Such gamepads include the Logitech Chillstream. Works in Linux.
|-
| WiseGroup.,Ltd SmartJoy Dual PLUS Adapter (dual PSX to USB joypad adapter)
| Not required
| Standard-A
| USB 1
| 100mA
| Standard-A port via USB 1-compatible High Speed Hub
| {{Yes}}
| ID 6677:8802. Works in Linux.
|-
| Logitech Cordless RumblePad 2
| Not required
| Standard-A
| Low speed
| 100mA
| Standard-A port via High Speed Hub
| {{Yes}}
| Product-ID: 0xc219, Vendor-ID: 0x046d (Logitech Inc.), [http://www.logitech.com/support/287 Official product support website], All buttons worked fine in PCSX, analog sticks not tested, but likely work"
|-
|}

== Touchpads ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.logitech.com/en-us/mice-pointers/mice/devices/8417 Logitech Wireless Touchpad]
| Not required
| Standard-A
| {{Unknown}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| Left and right four-finger swipes aren't mapped to anything by default in XFCE. They can be mapped as keyboard shortcuts.
|}

== Graphics tablets ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Works on Pandora
! Additional comments
|-
| Bamboo Multitouch
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__881806]}}
| It's not known if this works in Linux.
|-
| Genius Tablet
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes, [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__883140 via USB hub]}}
| It's not known if this works in Linux.
|-
| Wacom CTH-460
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__924422]}}
| Would need a patched driver to work. It's not known if this works in Linux.
|-
| Wacom Volito2 Tablet (Model: CTF-420)
| Not required
| Standard-A
| Low speed
| 40mA [http://www.my-volito.com/volito/specs.asp?lang=en]
| {{No}}
| USB ID: 056a:0062
|}

== Mice ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Works on Pandora
! Additional comments
|-
| Apple Mouse (M5769)
| USB
| {{No}}
| Seems to disable USB port, reboot afterwards required
|-
| Apple Mouse with Scroll Ball (A1152)
| USB
| {{Yes|Yes, needs a USB hub.}}
|
|-
| Cherry Ghostcord [http://www.amazon.de/Cherry-M85-26005DE-2-B-Unlimited-Home-Rechargeable/dp/B001EDSE0U/ref=tag_stp_s2_edpp_url]
| USB
| {{Yes|Yes, needs a USB hub.}}
| Part of a bundle with keyboard and a USB dongle for the connetion. With the dongle on the hub both devices work just fine (tested in XFCE)
|}

= Connectors, adapters, and hubs =

This section is intended as a general guide. Items in this section are standard USB accessories, so drivers are not required. Compatibility with Pandora is assumed. Please note that any external product links are provided for reference only, and are not an endorsement.

== OTG (On The Go) Adapters ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Generic adapter
| {{No}}
| [http://shop.ebay.com/?_from=R40&_trksid=p3907.m38.l1313&_nkw=usb+otg+host+cable&_sacat=See-All-Categories Find on eBay] [http://www.amazon.co.uk/s/ref=nb_ss_ce?url=search-alias%3Delectronics&field-keywords=OTG+Cable+Adapter&x=3&y=23 Find on Amazon] These links are not 100% accurate. Check for `mini-a`, and on eBay, the price is higher by about $8.
|-
|Hama 00074214
| {{Yes}}
|[http://www.hama.de/00074214/hama-mini-usb-adapter-mini-usb-a-plug-usb-a-socket-015-m Manufacturer Page]
|-
| Nokia USB OTG adapter
| {{Yes}}
| [http://www.electronicproductonline.com/catalog/product_info.php?cPath=35_67&products_id=2043 Electronic Product Online]
|}

== Compact USB Hubs ==

Be sure to enable USB-host!

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Griffin SmartShare USB [http://www.griffintechnology.com/products/smartshare-usb]
| {{No}}
|
|-
| Belkin F5U415 4 Port USB 2.0 Swivel Hub [http://catalog.belkin.com/IWCatProductPage.process?Product_Id=377085]
| {{No}}
| Comes with an optional power adapter.
|-
| Belkin F5U700 USB 2.0 7-Port Lighted Hub [http://www.belkin.com/uk/support/article/?lid=enu&pid=F5U700ea&aid=10289&scid=947]
| {{Yes}}
| Tested 2012-06-16 by [[user:spiralofhope|spiralofhope]] both with and without its power adapter.
|-
| Belkin F5U701 USB 2.0 7 Port Mobile Hub [http://www.belkin.com/IWCatProductPage.process?Product_Id=369788]
| {{Yes}}
| Tested by pabloh. Comes with an optional power adapter.
|-
| ID 0e8f:0016 GreenAsia Inc.
| {{No}}
| Tested by tsh. Labeled as high speed. Bought from ebay.
|-
| ID 05e3:0608 Targus with Genesys Logic 4 Port USB 2.0 Hub
| {{Yes}}
| Tested by Kazuki. Works.
|-
|Trust 4 port netbook hub ID 05e3:0608
| {{Yes}}
| Tested by tsh. Bought from [http://www.amazon.co.uk/gp/product/B0025X16AS Amazon].
|-
| High Speed 4 Port Mini USB 2.0 Hub for Laptop PC (non powered)
| {{Yes}}
| Octopus-style small cheap unpowered USB hub. Bought from [http://cgi.benl.ebay.be/ws/eBayISAPI.dll?ViewItem&item=270538502843 ebay]
|-
| Keeptech USB 2.0 Hub (7 Ports) with Power Adapter, KT-UH703 [http://www.keeptech.com/books_show.php?id=144]
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works powered or unpowered.
|-
| Logitech Premium 4-Port USB Hub [http://www.logitech.com/en-in/notebook-products/usb-hubs/devices/3048]
| {{Yes}}
|
|-
| LUPO 7-port USB 2.0 Hub (cheap octopus type which can be powered as there is dc socket)
| {{Partial|Yes. {{HideableNotes|Can use a power supply but wasn't tested with one.}}}}
| Tested by kilowatt. Bought from [http://www.amazon.co.uk/gp/product/B003BVDABG/ref=oss_product from amazon uk]
|-
| LogiLink USB 2.0 Hub 4-Port UA0086 [http://www.logilink.eu/showproduct/UA0086.htm]
| {{Yes}}
| Tested by Jones. Comes with an optional power adapter.
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php]
| {{Yes}}
| See [http://pandorawiki.org/USB_compatibility_list#USB_to_Ethernet_adapters USB to ethernet adapters] for more details. USB 1 devices work perfectly. Also available as other brands: [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Rosewill RHB-220 4-port USB 2.0 Hub
| {{Yes}}
| Tested by Tyrant1919. Unpowered. Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16817182168 Newegg].
|-
| i-rocks SLEEK HUB USB 2.0 4 Ports Hub [http://www.i-rocks.com/Product_detail.aspx?CLASS_ID=1036&PRODUCT_ID=1080]
| {{Yes}}
| Comes with an ac adapter, but can be used without. USB 1 devices work perfectly.
|-
| MSI StarHub201
| {{Yes}}
| Testet by mclien with keyboard and mouse in XFCE, unpowered, not on the MSI site (discontinnued, guess) [http://alatest.dk/anmeldelser/hubs-og-switches/msi-star-hub-201/po3-34222999,42/]
|}

[[Category:USB]]
[[Category:List]]

USB compatibility list

2013-04-20T16:46:59Z

Porg: /* Input devices */

This is a list of USB devices that have been tested on the Pandora. If the device you want to know about isn't listed here, don't worry! Just go to [[USB_reference|the USB reference page]], look up the specs of your device, and you may be able to figure out if it's compatible.

= Troubleshooting =

Each type of device will have its own unique way to troubleshoot.

But here are some general tips:

* Is USB-Host enabled?
* check <tt>lsusb</tt>
* check <tt>dmesg</tt>

When asking for help on [http://boards.openpandora.org/index.php?/forum/8-support/ the forums support board], be sure to post both your <tt>lsusb</tt> and <tt>dmesg</tt>.

Because <tt>dmesg</tt> output is very long, you need to paste it within [spoiler] tags like this:

[spoiler]
(paste your dmesg in here)
[/spoiler]

An easy way to get your <tt>dmesg</tt> so you can easily copy and paste it, is:

dmesg|leafpad

<tt>leafpad</tt> will open with the output of <tt>dmesg</tt>.

If you have no networking on your palmtop, you can send the information to a text file like this:

cd (your storage card)
dmesg>textfile.txt
sync

Then you can remove your card (if no programs are using it or PNDs are running on it) and bring it to a card reader on your desktop.

= Networking =

Please see the [[Mobile broadband]] page for tips on how to get these working, as well as [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/ this tutorial] from the GP32X forum.

== HSDPA (3G) Modems ==

Please note that many (if not all) USB 3G modems need modemmanager to be installed for switching from mass storage mode to serial communications mode. When first plugged in, most 3G USB modems claim to be a mass storage device and offer, on its built-in flash, drivers and connectivity software to be installed. Mostly this is only for Windows and Mac, so for the Pandora this is not useful. modemmanager instantly takes care of toggling the mode, so that when you plug in the modem, after a few seconds or maybe half a minute modemmanager has switched the modem to communications mode and NetworkManager is able to use it.

If you are using a Firmware before HF7 (or one of its Alpha/Beta versions) you have to install modemmanager. To do so, connect your Pandora to the Internet, open a terminal and, as a super user, intall it via opkg by entering the commands:

:sudo opkg update
:sudo opkg install modemmanager

'''Note:''' If you are using a firmware more recent than "Zaxxon" Hotfix 6 (starting with HF7) you do not have to follow the steps outlined above since modemmanager comes preinstalled.

'''Note 2:''' After plugging in the USB 3G modem, it may take some time until NetworkManager is able to use the modem. Wait for at least half a minute, until you give up and report that the modem doesn't work.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| ZTE K3565-Z / MF626 / MF627 / MF636
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__956513] [http://boards.openpandora.org/index.php?/topic/7226-superzaxxon-beta-11-released/page__pid__127881#entry127881]}}
| A how-to by shideneyu for this modem can be found [http://www.pandorawiki.org/ZTE_K3565Z_3G_USB_Modem here]
|-
|-
| BandLuxe C270
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| A how-to by relliker for this modem can be found [http://www.pandorawiki.org/BandLuxe_C270_3G_USB_Modem here]
|-
| Huawei E156G
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/52827-3gumts-usb-dongle/page__view__findpost__p__835681]}}
|
|-
| Huawei E160
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong. This one definitely needs modemmanager. After installing modemmanager, it works flawlessly.
|-
| Huawei E160E
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| As the entry for Huawei E220 was wrong, this Current draw could also be wrong.
|-
| Huawei E1750
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__939350]}}
|
|-
| [[wikipedia:Huawei E220|Huawei E220]]
| Not required
| Standard-A
| USB 1.1
| 500mA
| Standard-A port via High Speed hub
| {{No|Not on new kernels.}}
| The successful Pandora E220 tests were done by DJWillis on an old kernel (long before Pandora shipped). It seems that they are NOT working any more. Also tested on Linux (was it working?) This entry originally said 250mA, but there is no source and current sources say 500mA.
|-
| 4G-Systems XS Stick P14
| Not required (usbserial module)
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/54318-guide-mobile-broadband-usb-stick-usage/page__view__findpost__p__937681]}}
| Requires usbmodeswitch program.
|-
| iPhone 3GS (Probably also 1G/3G)
| ipheth
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Maybe|Should work in Angstrom with some work.}}
| Requires a good bit of dependencies to get working. Tested with Debian from SD, but should work in Angstrom with some work. The ipheth wwan0 device only provides a connection over the 3G modem, even if you're connected to a wifi network. I used the iproxy and SSH tunneling method with proxychains to get to the wifi network.
|-
| HTC Desire
| not required
| Standard-A
| USB 2.0
| 500mA
| {{Unknown|USB A (Standard-A port?)}}
| {{Yes}}
| Requires internet connection sharing to be enabled from the phone.
|}

== USB to Ethernet adapters ==

To enable USB Ethernet adapters on the Pandora, you may need to left-click the networking icon on the panel in Xfce, and select "Ifupdown (bnep0)".

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Mbps
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Apple USB Ethernet Adapter MB442Z/A
|
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Reportedly uses an ASIX AX88xxx chipset.
|-
| Apple USB Ethernet Adapter model A1277
|
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 05ac:1402 Apple, Inc.
|-
| ASUS USB Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0b95:7e2b ASIX Electronics Corp. AX88772B
|-
| Conrad 3-Port-USB-Hub und Netzwerk-Adapter
|
| Not required
| Standard-A
| USB 2.0
| A lot! {{HideableNotes|50% of battery charge only brings you 2h40min (min brightness, no other devices attached)}}
| Standard-A port
| {{Yes}}
| Has a 3port USB Hub included. External power supply can (and should) be attached, not included though. ASIX Chipset. 20€ @ [http://www.conrad.de/ce/de/product/976406/NOTEBOOK-MINI-DOCKINGSTATION-USBRJ45/SHOP_AREA_32315&promotionareaSearchDetail=005 Conrad Electronics]. Not tested in Linux.
|-
| Logitec USB 2.0 LAN-GTJ/U2B Ethernet adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) 1000Mbps=350mA 100Mbps=230mA 10Mbps=220mA(documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.logitec.co.jp/products/lan/langtju2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2B Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 100Mbps=170mA 10Mbps=210mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp.[http://www.logitec.co.jp/products/lan/lantxu2b/index.php]
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA (lsusb) 300mA (documentation)
| Standard-A port
| {{Yes}}
| ID 0b95:772a ASIX Electronics Corp. USB hub current: 100mA (lsusb) 200mA (documentation). [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php] [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Wii USB 2.0 10/100M adapter (use [http://www.asix.com.tw/products.php?op=pItemdetail&PItemID=86;71;101 ASIX AX 88772 USB 2.0 chip])
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772. [http://www.dealextreme.com/details.dx/sku.5926 This clone from DealExtreme] works too.
|-
| Connectland USB 2.0 10/100M Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 250mA
| Standard-A port
| {{Yes}}
| ID 0b95:7720 ASIX Electronics Corp. AX88772 - Works fine, Sometimes a reboot is necessary (ZaxxonHF5RC1).
|-
| Belkin Gigabit USB 2.0 Network Adapter
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| The shape of it make is a bit awkward to fit if you connect it directly, but it has a short adapter cable. I only get ~95Mbit on a gigabit network, but then the pandora's cpu maxes out. (it may be that the driver/usb stack isn't very well optimized), has horribly bright blue LEDs.
|-
| MosChip MCS7830 USB 10/100 Ethernet adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Kernel module: mcs7830.
|-
| EU.MARK USB 10/100M RJ45 Ethernet Network Adapter Dongle
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| USB ID: 9710:7830 - bought from [http://www.dealextreme.com/details.dx/sku.22684 DealExtreme]
|-
| Digitus DN-10050 Fast Ethernet USB Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| MosChip MCS7830-based adapter. USB ID 9710:7830.
|-
| Edimax EU-4230 Fast Ethernet USB Adapter with 3-port USB hub [http://edimax.ie/images/Image/datasheet/USB/EU-4230/EU-4230_Datasheet.pdf]
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Ethernet USB ID 0b95:772a ASIX Electronics Corp. 3-port USB2.0 hub USB ID 0409:005a NEC Corp. Optional power adapter for USB hub.
|-
| Peabird USB v2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Yes}}
| ID 9710:7830 MosChip Semiconductor MCS7830 10/100 Mbps Ethernet adapter. Consumes a lot of current. Fragile, the protective plastic cord cracked after one month. Hot. A blue light a bit too flashy. Definitely avoid this model.
|-
| SIIG JU-NE0012-S1 USB 2.0 Fast Ethernet Adapter
| 10/100
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{Yes}}
| Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16812191163 Newegg]
|-
| TRENDnet USB to Gigabit Ethernet Adapter TU2-ETG
| 10/100/1000
| Not required
| Standard-A
| USB 2.0
| 450mA (lsusb) Dormant: 5mA Static: 91mA Working: 131mA (documentation)
| Standard-A port
| {{Yes}}
| Rev. 2.0R ID 0b95:1780 ASIX Electronics Corp. AX88178 [http://www.trendnet.com/products/proddetail.asp?prod=275_TU2-ETG&cat=42] Rev. 2.0R is white, previous versions are blue and consumes more current. The documentation's current draw are reported for 10 and 100Mbps.
|-
| Novatel Wireless Jetpack 4620L
|
| cdc_ether
| Standard-A
| USB
| High drain; 95% charge = 6:00 battery life.
| Standard-A port
| {{Yes}}
| This is a LTE/EVDO/CDMA/HSPA/UMTS/EDGE/GPRS Wifi Hotspot device; Device is registered as a USB Ethernet device when connected through USB tethered (as opposed to Wifi) connection. USB ID 1410:b008
|}

== USB to serial adapters ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| pl203
| usbserial
| Standard-A
| USB 1.1
| 100mA. A powered hub is needed.
| Standard-A port
| {{Yes}}
| A powered hub is needed. Plug the device, then load USB modules. ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port.
|}

== USB WiFi adapters ==

The Pandora stock kernel may not come with all wireless driver support outside of the internal WiFi chip. Sometimes, the only way you'll get wireless working is to build your own kernel with it included or try [http://wireless.kernel.org/en/users/Download compat-wireless].

As for hofix 6a4 compat-wireless seems to be present in the kernel out of the box, so one can build a USB wireless driver for Pandora following this [http://boards.openpandora.org/index.php?/topic/5140-solvedbuilding-a-usb-wifi-driver/page__view__findpost__p__89280 algorithm]

As for [[hotfix 6]] Release Candidate the kernel includes drivers for these Realtek chips: RTL8712/8188/8191/8192SU/8192CU

See also [http://boards.openpandora.org/index.php?/topic/7160-micro-wifi-dongle/ this thread] on the forums for the latest.

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| Advance Mini Wireless N150
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| There's a little hole on it, so it's useful for attaching it to the OP.
|-
| ASUS WL-167G v2
| rt73usb + rt2x00usb + rt2x00lib
| Standard-A
| USB 2.0
| 300mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 0b05:1723 ASUSTek Computer, Inc. WL-167G v2 802.11g Adapter [Ralink RT73]. Works pretty fine on Linux PC.
|-
| Belkin N1 Wireless USB Adapter (F5D8051) ("Ver. 2053") (MARVELL v1021)
| N/A
| Standard-A
| USB 2.0
| {{Unknown}}
| No connection was attempted.
| {{No|No native driver support and ndiswrapper obviously won't work.}}
| There's a previous revision of this dongle which is supposed to have a Ralink chip, but they revised it and put a different chip inside. Reported (by whom?) to work with ndiswrapper and works in Linux.
|-
| Belkin Surf micro
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Cisco/Linksys AE1000 High Performance Wireless-N USB Adapter
| rt3572sta (RT3572USB)
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A (Standard-A port?)
| {{Yes|Works with a modified driver.}}
| (Compiled module for pandora:[http://boards.openpandora.org/index.php?/topic/1992-linksys-ae1000-usb-wifi/ pandora forum]) Download the driver from [http://www.ralinktech.com/support.php?s=2 ralink's driver site], edit ./common/rtusb_dev_id.c, before "#endif // RT2870" add "{USB_DEVICE(0x13B1,0x002F)},", compile.' Reported (by whom?) to work in Linux.
|-
| D-Link WIRELESS G USB ADAPTER DWL-G122 rev.E1 F/W 5.00
| rt2870sta + rt2800usb + rt2800lib
| Standard-A
| USB 2.0
| 450mA
| USB A
| {{Yes|Works under Slackware, not (without a hub) under Zaxxon, which become very unstable}}
| 07d1:3c0f D-Link System AirPlus G DWL-G122 Wireless Adapter(rev.E) [Ralink RT2870]. Works pretty fine on Linux PC.
|-
| Digitus Wireless 150N USB 2.0 Adapter
| rtl8192cu
| Standard-A
| USB 2.0
| 500mA
| USB A
| {{Yes|Yes}}
| Bundled with a non-WiFi Pandora coming from Craig's shop
|-
| Edimax EW-7811Un
| rtl8192cus
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Netgear WNA1000M
| rtl8192cu
| Standard-A
| USB 2.0
| {{Unknown}}
| USB A
| {{Yes|Yes}}
| {{Yes|Should work out of the box since [[Hotfix 6]] Release Candidate}}
|-
| Thomson WLG-1500A
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|Doesn't work.}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter
|-
| TRENDnet TEW-424UB V2
| ?
| Standard-A
| USB 2.0
| 400mA
| USB A
| {{No|lsusb shows it, but no module is loaded}}
| 0457:0163 Silicon Integrated Systems Corp. 802.11 Wireless LAN Adapter. Same behavior on a PC.
|-
| Alfa Network AWUS036H 1000mw
| RTL8187
| IEEE 802.11b/g
| USB 2.0
| ?
| USB A
| {{Yes|Yes}}
| can be found on ebay; tested with Beta 3
|-
| TP-Link 150Mbps Mini Wireless N
| rtl8192cu
| Standard-A
| USB 2.0
| Unknown
| USB A
| {{Yes|Yes}}
| Model No TL-WN723N. Tested with WPA2. Works out of the box. Cheap to buy (£6.99 from pcworld in the UK).
|-
|}

== DVB/TNT/TDT ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Module(s)
! Firmware
! Additional comments
|-
| AVerMedia AVerTV Volar Green HD
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| Should work
| af9033 tda18218
| dvb-usb-af9035-02.fw
| ID 07ca:a835 AVerMedia Technologies, Inc.
HD/PRO (A835)
|-
| AVerMedia AVerTV Volar Video Capture
| Standard-A
| USB 2.0
| Reported as 0mA. More likely to be 500mA
| Standard-A port
| ?
| ?
| ?
| ID 07ca:4830 AVerMedia Technologies, Inc.
H830
|-
| Hauppauge WinTV aero
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes|Yes}}
| smsmdtv
| sms1xxx-hcw-55xxx-dvbt-02.fw
| ID 2040:b900 Hauppauge . Also works on the mini-usb port.
|-
| MSI Digi Vox Min
| Standard-A
| USB 2.0
| ?
| Standard-A port
| {{Yes|Yes}}
| ?
| ?
| Realtek rtl2832u chipset
|-
|}

= Storage =

== External Hard Disk Drives ==
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! style="min-width: 120px" | Works on Pandora
! Additional comments
|-
| Freecom 250GB 2.5" portable
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Inside it's a Samsung Model HM251JX. {{HideableNotes|So I guess anything based on that will also work OK.}}
|-
| (Intenso)® 2.5" MEMORYSTATION 1TB
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
|
|-
| LaCie Rikiki 250GB USB 2.0 2.5" Hard Drive
| Not required
| standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port via powered High Speed Hub
| {{Partial|Not when unpowered, needs testing with a powered hub}}
| Not only does it fail to spin up, but it causes the Pandora's screen to pulsate wildly, much like an old CRT would if you placed a speaker or a magnet near to it. Not tested with a powered hub.
|-
| Seagate Seagate® Expansion™ External Drives
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{No}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14781-hitnrun/ Hitnrun]. "Isn't even detected in lsusb (drive powered by external power source)"
|-
| Verbatim 250GB Model #47580 Hard Drive
| Not required
| Direct
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877512 almatuk]. {{HideableNotes|"Watched videos directly from it at full speed, no need for powered USB hub. Had issues playing roms directly off it however as it was formatted NTFS. I'm sure if I formatted to FAT32 these would disappear."}}
|-
| Western Digital 160GB Elements External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| standard-A port via powered High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB Elements Portable USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or standard-A port via High Speed Hub
| {{Yes}}
|
|-
| Western Digital 250GB My Passport Essential USB 2.0 2.5" Hard Drive
| Not required
| {{Unknown|Direct?}}
| USB 2.0
| {{Unknown}}
| {{Unknown|Direct?}}
| {{Partial|Maybe}}
| Tested by TheDarkSpectrum48K. The first time it [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__877386 "works perfectly!"]. The second time [http://www.gp32x.com/board/index.php?/topic/54509-dont-use-lacie-25-usb-hard-disk-drives-with-a-pandora/page__view__findpost__p__882635 it didn't work].
|-
| Western Digital 400GB My Passport Essential USB 2.0 2.5" HDD model WDME4000TE
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14534-peca/ Peca].
|-
| Western Digital 500GB Elements Portable External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. {{HideableNotes|The USB cable that came with it was bad, so I used another one.[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949863]}}
|-
| Western Digital 500GB My Passport Essential External Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works fine. {{HideableNotes|Came pre-formatted in NTFS, but should work if you downloaded the community codec pack. It said 1TB on the packaging, but there was 465GB free space, so I'm pretty sure it was actually the 500GB one.}}[http://www.gp32x.com/board/index.php?/topic/59494-solved-how-do-i-get-my-wd-500gb-external-hard-drive-to-work-properly/page__view__findpost__p__949645]
|-
| Western Digital 1TB My Passport Essential SE External USB 2.0 2.5" Hard Drive
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct or through powered High Speed Hub
| {{Yes}}
| Tested by [http://http://www.gp32x.com/board/index.php?/user/19191-mycohl/ Mycohl]. {{HideableNotes|Externally powered hub recommended to conserve battery power.}}
|-
| Western Digital Elements 2TB 3.5" Hard Drive Model:WDBAAU0020HBK
| Not Required
| Standard-A
| USB 2.0
| {{Unknown}}
| Direct
| {{Yes}}
| Tested by [http://boards.openpandora.org/index.php?/user/430-kilowatt/ kilowatt].
|}

== DVD/CD Drives ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Lite-On EZ-DUB DVD/CD Multi-Recorder (Model eZAU120)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter - DC 12V 1.8A
| Standard-A port
| {{No}}
| Works in Linux.
|-
| Memorex 20x Multi Format DVD Recorder External - DVD±RW (±R DL)
| Not required
| Standard-A
| USB 2.0
| Powered by included mains adapter
| Standard-A port
| {{Yes}}
|
|}

= Video display device =

== VGA DVI HDMI adapter ==

No devices have been tested yet

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
|
|
|
|
|
|
|
| No devices have been tested yet
|}

==== External graphics cards ====

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Output connectors
! Works on Pandora
! Additional comments
|-
| Tritton see2 usb 2.0 to SVGA adapter
| sisusb
| USB
| USB 2.0
| {{Unknown|High {{HideableNotes|Reduces Pandora's battery life in half (10h → 4h)}}}}
| VGA (D-SUB)
| {{Partial|Yes, but has performance issues.}}
| Needs to be integrated with preferences. {{HideableNotes|Currently I (who?) must edit xorg.conf and mess with xinerama.}} Good for presentations, dragging a window is bearable, but hi-res video is slow. Works in Linux without any issues.
|-
| DisplayLink usb 2.0 to SVGA adapter WS Tech USB-DVI
| udlfb
| USB
| USB 2.0
| 500mA
| VGA (D-SUB)
| Yes
| 17e9:0198 DisplayLink. No hub needed. Module and userspace here:
git clone http://git.plugable.com/webdav/udlfb/
git clone http://git.plugable.com/webdav/xf-video-udlfb/
|-
| Magic Control Technology Corp. Trigger II External Graphics
| sisusb
| USB
| USB 2.0
| 500mA
| ?
| ?
| ID 0711:5200 Magic Control Technology Corp. A kernel recompile is needed. In /usr/src/linux/drivers/usb/misc/sisusbvga , edit sisusb.c , and add

{ USB_DEVICE(0x0711, 0x5200) },

in the list around line 3250
Get the latest xf86-video-sisusb driver here:
http://xorg.freedesk...ividual/driver/

|}

= Video capture devices =

== Webcams ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Exoo No Driver/USB 2.0 Webcam (Model No.: M053)
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| Bought from [http://www.dealextreme.com/details.dx/sku.14991 DealExtreme]. Works in Linux.
|-
| Logitech Quickcam Communicate Deluxe
| Not required
| Standard-A
| USB 2.0
| {{Unknown}}
| Standard-A port
| {{No}}
| USB ID: 046d:0992, works though [http://linux-uvc.berlios.de/ uvcvideo]. Works in Linux.
|-
| Logitech HD Webcam C270 720p
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0825 Logitech, Inc. Audio recognized, but not tested. More info to come. Works in Linux.
|-
| Logitech HD Webcam Pro 9000
| Not required
| Standard-A
| USB 2.0
| 500mA
| Standard-A port
| {{Partial|Yes, but audio untested}}
| ID 046d:0990 Logitech, Inc. Audio recognized, but not tested. Great Picture! Works in Linux.
|}

= Audio devices =

== Microphones/recorders ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.bluemic.com/yeti/] Blue Yeti
| not required
| standard-A
| unknown
| unknown
| standard-A port via High Speed USB hub
| {{unknown|Not thoroughly tested.}}
| Very roughly tested 2012-06-13 by [[user:spiralofhope|spiralofhope]] using Mumble. More testing required. {{HideableNotes|The system recognizes the Yeti, and it appears in Mumble's list of available devices, but the audio wizard doesn't show the Yeti as having input. Additional troubleshooting is required, as is checking the manual/company website for missing information.}}
|-
| [http://www.zoom.co.jp/english/products/h2/] Zoom H2 Handy Recorder
| not required
| standard-A
| USB 1.1
| 300mA
| standard-A port via High Speed USB hub
| {{Yes|Yes, needs a USB hub.}}
| Can record into Audacity, but won't be recognized unless connected through USB hub.[http://www.gp32x.com/board/index.php?/topic/59301-audacity-1-3-12/page__view__findpost__p__947602].
|}

== MIDI controllers ==

EvilDragon bundled the usb MIDI class drivers in the default firmware image, therefore ANY class-compliant MIDI device should work with the Pandora, out of the box.[http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Akai LKP25
| Not required
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes [http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432]}}
|
|-
| M-Audio MIDISPORT 2x2 Anniv
| Not required
| {{Unknown}}
| {{Unknown}}
| 400mA
| {{Unknown}}
| {{Unknown}}
| ID 0763:1050 Midiman. High current draw!
|-
|}

== USB audio controllers ==

Some are "professional soundcard"; see [http://en.wikipedia.org/wiki/Sound_card#Professional_soundcards_.28audio_interfaces.29 definition on Wikipedia].

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| Cakewalk UA-1G
| not required
| Standard-A
| USB 2.0
| 200mA
| Standard-A port
| {{Yes}}
| ID 0582:00e9 Roland Corp. This device may be similar to older Edirol/Roland USB audio devices. Runs and record under Slackware. Jack audio server realtime recording works. Recognized but not tested under official OS. A hub, powered or not, is needed.
|-
| Connectland AUDIO ADAPTER
| not required
| Standard-A
| USB 2.0
| 100mA
| Standard-A port
| {{Yes}}
| ID 0d8c:000c C-Media Electronics, Inc. Audio Adapter . CMedia CM108 Virtual 7.1 Channel Sound. Has vol +, vol -, mute headspeaker, mute mic buttons. Mini-jack audio in and out. A non-powered hub is needed.
|}

= Input devices =

Any HID ([http://en.wikipedia.org/wiki/Human_interface_device Human Interface Device]) compliant keyboard, mouse or game controller should work on the Pandora. Most of those device are low speed or full speed USB device and will need to be connected though either a [[USB_reference#OTG host mode|USB OTG adapter/cable]] or a [[USB reference#What’s all this stuff about USB 1.1 and USB 2.0? Isn’t USB, uh, universal?|USB2 hub]] in order to work on the Pandora.

== External Game Controllers ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested on Pandora
! Additional comments
|-
| 2-TECH SNES-to-USB adapter
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| USB description is "HuiJia USB GamePad", <tt>lsusb</tt> calls it "0e8f:3013 GreenAsia Inc."
|-
| USB Super RetroPort (SNES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=29 RetroZone]. Works in Linux.
|-
| USB RetroPort (NES-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=28 RetroZone]. Works in Linux.
|-
| Trio Linker Plus II (PlayStation,-GameCube,-and-Dreamcast-to-USB adapter)
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Bought from [http://www.play-asia.com/paOS-13-71-6m-49-en-70-1zfv.html Play-Asia]. Works in Linux.
|-
| NAZAR V47 USB Force Feedback Vibrating Gamepad Controller for PC
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.24551 DealExtreme]. Works in Linux.
|-
| 10-Fire-Button Double Vibration Feedback USB PC Arcade Joystick
| Not required
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| Whether it really contains the claimed force feedback feature is unknown as this feature does not work under Linux - bought from [http://www.dealextreme.com/details.dx/sku.27821 DealExtreme]. Works in Linux.
|-
| Official PlayStation 3 controller
| Not required
| Standard-A
| Full speed
| {{Unknown}}
| USB A To Mini B Cable via High Speed Hub
| {{No}}
| This is for USB not bluetooth compatibility. Sixaxis and DualShock not tested. Works in Linux.
|-
| Saitek PLC Cyborg Force Rumble Pad (P2500) - 06a3:ff0c
| {{unknown}}
| Standard-A
| {{unknown}}
| 5V
| Standard-A port via High Speed Hub
| {{Unknown|Not fully tested}}
| Partial test attempted 2012-06-24 by [[user:spiralofhope|spiralofhope]]. lsusb lists it. More testing required. {{HideableNotes|A gamepad testing procedure needs to be defined. See [[Joystick testing]].}}
|-
| Thrustmaster Firestorm Digital 3 Gamepad
| Not required
| Standard-A
| Low speed
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| ID 07b5:0213 Mega World International, Ltd Thrustmaster Firestorm Digital 3 Gamepad.
|-
| Wired Xbox 360 Controller
| xpad module
| Standard-A
| {{Unknown|Probably USB 1.1}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{No}}
| This also includes gamepads for PC that needs the Windows Xinput driver. Such gamepads include the Logitech Chillstream. Works in Linux.
|-
| WiseGroup.,Ltd SmartJoy Dual PLUS Adapter (dual PSX to USB joypad adapter)
| Not required
| Standard-A
| USB 1
| 100mA
| Standard-A port via USB 1-compatible High Speed Hub
| {{Yes}}
| ID 6677:8802. Works in Linux.
|}

== Touchpads ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Works on Pandora
! Additional comments
|-
| [http://www.logitech.com/en-us/mice-pointers/mice/devices/8417 Logitech Wireless Touchpad]
| Not required
| Standard-A
| {{Unknown}}
| {{Unknown}}
| Standard-A port via High Speed Hub
| {{Yes}}
| Left and right four-finger swipes aren't mapped to anything by default in XFCE. They can be mapped as keyboard shortcuts.
|}

== Graphics tablets ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Driver
! Connector
! Supported standard
! Current draw
! Works on Pandora
! Additional comments
|-
| Bamboo Multitouch
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__881806]}}
| It's not known if this works in Linux.
|-
| Genius Tablet
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Yes|Yes, [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__883140 via USB hub]}}
| It's not known if this works in Linux.
|-
| Wacom CTH-460
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{Unknown}}
| {{No|No [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__924422]}}
| Would need a patched driver to work. It's not known if this works in Linux.
|-
| Wacom Volito2 Tablet (Model: CTF-420)
| Not required
| Standard-A
| Low speed
| 40mA [http://www.my-volito.com/volito/specs.asp?lang=en]
| {{No}}
| USB ID: 056a:0062
|}

== Mice ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Connector
! Works on Pandora
! Additional comments
|-
| Apple Mouse (M5769)
| USB
| {{No}}
| Seems to disable USB port, reboot afterwards required
|-
| Apple Mouse with Scroll Ball (A1152)
| USB
| {{Yes|Yes, needs a USB hub.}}
|
|-
| Cherry Ghostcord [http://www.amazon.de/Cherry-M85-26005DE-2-B-Unlimited-Home-Rechargeable/dp/B001EDSE0U/ref=tag_stp_s2_edpp_url]
| USB
| {{Yes|Yes, needs a USB hub.}}
| Part of a bundle with keyboard and a USB dongle for the connetion. With the dongle on the hub both devices work just fine (tested in XFCE)
|}

= Connectors, adapters, and hubs =

This section is intended as a general guide. Items in this section are standard USB accessories, so drivers are not required. Compatibility with Pandora is assumed. Please note that any external product links are provided for reference only, and are not an endorsement.

== OTG (On The Go) Adapters ==

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Generic adapter
| {{No}}
| [http://shop.ebay.com/?_from=R40&_trksid=p3907.m38.l1313&_nkw=usb+otg+host+cable&_sacat=See-All-Categories Find on eBay] [http://www.amazon.co.uk/s/ref=nb_ss_ce?url=search-alias%3Delectronics&field-keywords=OTG+Cable+Adapter&x=3&y=23 Find on Amazon] These links are not 100% accurate. Check for `mini-a`, and on eBay, the price is higher by about $8.
|-
|Hama 00074214
| {{Yes}}
|[http://www.hama.de/00074214/hama-mini-usb-adapter-mini-usb-a-plug-usb-a-socket-015-m Manufacturer Page]
|-
| Nokia USB OTG adapter
| {{Yes}}
| [http://www.electronicproductonline.com/catalog/product_info.php?cPath=35_67&products_id=2043 Electronic Product Online]
|}

== Compact USB Hubs ==

Be sure to enable USB-host!

{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 100%;"
|- style="background: #ececec"
! Device
! Works on Pandora
! Additional comments
|-
| Griffin SmartShare USB [http://www.griffintechnology.com/products/smartshare-usb]
| {{No}}
|
|-
| Belkin F5U415 4 Port USB 2.0 Swivel Hub [http://catalog.belkin.com/IWCatProductPage.process?Product_Id=377085]
| {{No}}
| Comes with an optional power adapter.
|-
| Belkin F5U700 USB 2.0 7-Port Lighted Hub [http://www.belkin.com/uk/support/article/?lid=enu&pid=F5U700ea&aid=10289&scid=947]
| {{Yes}}
| Tested 2012-06-16 by [[user:spiralofhope|spiralofhope]] both with and without its power adapter.
|-
| Belkin F5U701 USB 2.0 7 Port Mobile Hub [http://www.belkin.com/IWCatProductPage.process?Product_Id=369788]
| {{Yes}}
| Tested by pabloh. Comes with an optional power adapter.
|-
| ID 0e8f:0016 GreenAsia Inc.
| {{No}}
| Tested by tsh. Labeled as high speed. Bought from ebay.
|-
| ID 05e3:0608 Targus with Genesys Logic 4 Port USB 2.0 Hub
| {{Yes}}
| Tested by Kazuki. Works.
|-
|Trust 4 port netbook hub ID 05e3:0608
| {{Yes}}
| Tested by tsh. Bought from [http://www.amazon.co.uk/gp/product/B0025X16AS Amazon].
|-
| High Speed 4 Port Mini USB 2.0 Hub for Laptop PC (non powered)
| {{Yes}}
| Octopus-style small cheap unpowered USB hub. Bought from [http://cgi.benl.ebay.be/ws/eBayISAPI.dll?ViewItem&item=270538502843 ebay]
|-
| Keeptech USB 2.0 Hub (7 Ports) with Power Adapter, KT-UH703 [http://www.keeptech.com/books_show.php?id=144]
| {{Yes}}
| Tested by [[User:Esn|Esn]]. Works powered or unpowered.
|-
| Logitech Premium 4-Port USB Hub [http://www.logitech.com/en-in/notebook-products/usb-hubs/devices/3048]
| {{Yes}}
|
|-
| LUPO 7-port USB 2.0 Hub (cheap octopus type which can be powered as there is dc socket)
| {{Partial|Yes. {{HideableNotes|Can use a power supply but wasn't tested with one.}}}}
| Tested by kilowatt. Bought from [http://www.amazon.co.uk/gp/product/B003BVDABG/ref=oss_product from amazon uk]
|-
| LogiLink USB 2.0 Hub 4-Port UA0086 [http://www.logilink.eu/showproduct/UA0086.htm]
| {{Yes}}
| Tested by Jones. Comes with an optional power adapter.
|-
| Logitec USB 2.0 LAN-TX/U2H3S Ethernet adapter + 3 USB ports [http://www.logitec.co.jp/products/lan/lantxu2h3/index.php]
| {{Yes}}
| See [http://pandorawiki.org/USB_compatibility_list#USB_to_Ethernet_adapters USB to ethernet adapters] for more details. USB 1 devices work perfectly. Also available as other brands: [http://www.amazon.com/USB-2-0-3-Port-Ethernet-Adapter/dp/B002OFJRW6/ref=sr_1_3?ie=UTF8&qid=1357779881&sr=8-3&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Encore-ENUET-3USB-3-Port-Ethernet-Adapter/dp/B0036FZJX4/ref=sr_1_1?ie=UTF8&qid=1357779881&sr=8-1&keywords=USB+ethernet+with+3+port+USB+hub] [http://www.amazon.com/Addlogix-3-port-USB-Hub-Ethernet/dp/B0030DO7OY/ref=sr_1_27?ie=UTF8&qid=1357780088&sr=8-27&keywords=USB+ethernet+with+3+port+USB+hub]
|-
| Rosewill RHB-220 4-port USB 2.0 Hub
| {{Yes}}
| Tested by Tyrant1919. Unpowered. Bought from [http://www.newegg.com/Product/Product.aspx?Item=N82E16817182168 Newegg].
|-
| i-rocks SLEEK HUB USB 2.0 4 Ports Hub [http://www.i-rocks.com/Product_detail.aspx?CLASS_ID=1036&PRODUCT_ID=1080]
| {{Yes}}
| Comes with an ac adapter, but can be used without. USB 1 devices work perfectly.
|-
| MSI StarHub201
| {{Yes}}
| Testet by mclien with keyboard and mouse in XFCE, unpowered, not on the MSI site (discontinnued, guess) [http://alatest.dk/anmeldelser/hubs-og-switches/msi-star-hub-201/po3-34222999,42/]
|}

[[Category:USB]]
[[Category:List]]

Multisite username check

2013-03-25T13:36:19Z

Porg: board discussion link

This is a suggestion by [[User:Porg|Porg]]. Participation is welcome! Discussion takes place in [http://boards.openpandora.org/index.php/topic/6068-suggestion-open-pandora-scene-multisite-username-checker/ this thread].

In the user registration process at the various Open Pandora related sites (board, wiki, repo, bugtracker, …) [[User:Porg|Porg]] suggests to display the following hint:
----
'''Before registering your username''' here, you can run the [http://usernames.openpandora.org/check Pandora sphere username checker], which tests whether the username already exists within any other OpenPandora [http://usernames.openpandora.org/sites related sites]:
* '''As a courtesy to other users''', in order to not take their name away on other sites.
* '''For your own convenience''', to achieve a uniform nickname on all the OpenPandora sites, as a new arriving community member.
----

== ToDo ==

# Which Open Pandora relates websites (with user registration) are there? '''Anyone''' please add the URLs to the list below.
# Which site operators are willing to cooperate? '''Site operators''', please confirm your readiness, by writing your name plus short note next to the URL. Requirements for participating site operators:
## Offer a software interface (API) for testing whether a username exists at your site.
## Display the hint and link to or embed the checking service (iframe) into the registration page/process of your site.
# We need a web developer to create that multisite username checking service. '''Developer volunteers''', please participate in the [http://boards.openpandora.org/index.php?/topic/6068-suggestion-open-pandora-scene-multisite-username-checker/ discussion process], or enlist your dedication right below.

== Sites ==

URL of a Open Pandora related website which uses user registrations/logins + site operator(s) (nick)name and confirmation of participation + optional remarks:

===== Official Sites: =====

http://boards.openpandora.org/

http://repo.openpandora.org/

http://c4a.openpandora.org/ — Compo4all MAME - ladder/scoreboard competition for classic arcade games

===== Unofficial Sites: =====

http://pandorawiki.org/

http://gp32x.com/board/

http://pandorapress.net/

http://openhandhelds.org/

===== Alternate Language Sites: =====

http://wiki.openpandora.de/ (German)

http://forum.gp2x.de/ (German)

http://openpandora.jp/ (Japenese)

http://openpandora.info/ (russian)

http://www.opgaming.com/ (Italian)

http://openpandora-france.forumactif.net/ (French)

http://forum.gp2xtr.com/ (Turkish)

== Developers ==

Developers, who are willing to realize the multisite username checking service, please enlist your (nick)name and confirmation of participation plus optional remarks here:

[[Category:Ideas and proposals]]

Multisite username check

2013-03-25T13:12:40Z

Porg: /* Official Sites: */

This is a suggestion by [[User:Porg|Porg]]. Participation is welcome!

In the user registration process at the various Open Pandora related sites (board, wiki, repo, bugtracker, …) [[User:Porg|Porg]] suggests to display the following hint:
----
'''Before registering your username''' here, you can run the [http://usernames.openpandora.org/check Pandora sphere username checker], which tests whether the username already exists within any other OpenPandora [http://usernames.openpandora.org/sites related sites]:
* '''As a courtesy to other users''', in order to not take their name away on other sites.
* '''For your own convenience''', to achieve a uniform nickname on all the OpenPandora sites, as a new arriving community member.
----

== ToDo ==

# Which Open Pandora relates websites (with user registration) are there? '''Anyone''' please add the URLs to the list below.
# Which site operators are willing to cooperate? '''Site operators''', please confirm your readiness, by writing your name plus short note next to the URL. Requirements for participating site operators:
## Offer a software interface (API) for testing whether a username exists at your site.
## Display the hint and link to or embed the checking service (iframe) into the registration page/process of your site.
# We need a web developer to create that multisite username checking service. '''Developer volunteers''', please participate in the [http://boards.openpandora.org/index.php?/topic/6068-suggestion-open-pandora-scene-multisite-username-checker/ discussion process], or enlist your dedication right below.

== Sites ==

URL of a Open Pandora related website which uses user registrations/logins + site operator(s) (nick)name and confirmation of participation + optional remarks:

===== Official Sites: =====

http://boards.openpandora.org/

http://repo.openpandora.org/

http://c4a.openpandora.org/ — Compo4all MAME - ladder/scoreboard competition for classic arcade games

===== Unofficial Sites: =====

http://pandorawiki.org/

http://gp32x.com/board/

http://pandorapress.net/

http://openhandhelds.org/

===== Alternate Language Sites: =====

http://wiki.openpandora.de/ (German)

http://forum.gp2x.de/ (German)

http://openpandora.jp/ (Japenese)

http://openpandora.info/ (russian)

http://www.opgaming.com/ (Italian)

http://openpandora-france.forumactif.net/ (French)

http://forum.gp2xtr.com/ (Turkish)

== Developers ==

Developers, who are willing to realize the multisite username checking service, please enlist your (nick)name and confirmation of participation plus optional remarks here:

[[Category:Ideas and proposals]]

Nubs

2013-01-04T22:03:57Z

Porg: /* Nub Configuration */

The Pandora has 2 analogue controllers 'nubs', which were custom designed.

== Nub Calibration ==
[[Image:Nub_back.jpg|thumb|Backside]]
The nubs need time to calibrate at startup. Often this can be achieved by moving the nubs around once the Pandora has fully loaded (moving them while the OS is still loading may cause a calibration error). Re-calibration of the nubs can be achieved via 'Pandora Menu -> Settings -> Nubs', and selecting either configure <nub> or 'Restore default settings for both nubs'

===Nub Dance===
The 'Nub Dance' or 'Magic Nub Dance' is a technique used to calibrate the Pandora's nubs by exercising the nubs to their hardware limits.

Some of the older nubs required this calibration technique periodically, however newer nubs (since 2011) do not need as much calibration as the older ones.
Push them up, down, left, right to the edge, then let go of them so they spring back by themselves.
i.e. push up, as far as it will go, then let go (it must spring back). Do that for each direction. Then do some circles.
That should set them up. If you don't do this they can go wrong during that session until reset.[http://www.gp32x.com/board/index.php?/topic/54445-please-fix-the-right-anolog-nub-functions/page__view__findpost__p__876651]

===Nub firmware===
The proprietary algorithm for calibrating the nubs is contained within 8KB of flash ROM. More information [http://www.gp32x.com/board/index.php?/topic/53939-the-real-pandora-niche/page__view__findpost__p__865928 here].

===Using compressed air to remove dirt===
If you feel that you might be getting some nub problems caused by dirt having gotten inside, you can try blasting compressed air into the niche where the nubs meet the case. [http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__868440] [http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__871405][http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__872373][http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__872896]

==Nub Configuration==
(As of Zaxxon HF5) 
Nubs can be configured in software under Settings -> Nubs in the Xfce 4 menu system and can also be managed through the filesystem in the /proc/pandora/(nub0/nub1 for left and right nubs respectively).
Most files in that folder (mbutton_threshold, mouse_sensitivity, scroll_rate, scrollx_sensitivity, and scrolly_sensitivity) are fairly straightforward, containing a number determining the value of the attribute.

The only different field is in mode, which contains a string to determine how each nub behaves-

<pre>
mouse - The nub is treated as a mouse, the default configuration of the left nub.
mbuttons - The nub is used as the buttons of the mouse, the default configuration of the right nub.
scroll - The nub scrolls the screen vertically/horizontally as a pair of scroll wheels would.
absolute - The nub is treated as a joystick for the purposes of gaming.
mbscroll* - A combination of mbuttons and scroll. Up/down for scrolling up/down, left/right for according mouse buttons.
</pre>

<nowiki>*</nowiki>'''Note''': As of 2013-01-01 '''mbscroll''' is only available in an experimental kernel image. [http://boards.openpandora.org/index.php/topic/11295-idea-combined-nub-mode-2-mouse-buttons-scrolling-on-1-axis/ Concept] by porg, realization by urjaman ([http://boards.openpandora.org/index.php/topic/11295-idea-combined-nub-mode-2-mouse-buttons-scrolling-on-1-axis/?p=210868 download & instructions], [http://boards.openpandora.org/index.php/topic/11295-idea-combined-nub-mode-2-mouse-buttons-scrolling-on-1-axis/?p=210844 source code]).

The easiest way to alter a nub's mode in the console is to use the following code-
<source lang=bash>
echo "(mode)" > /proc/pandora/nubx/mode
</source>
Where (mode) is one of the above modes and the x in nubx is 0 or 1.

For example, if we wanted to set the left nub to scroll, we'd use
<source lang=bash>
echo "scroll" > /proc/pandora/nub0/mode
</source>
All information pulled from [http://www.pandorawiki.org/PND_nub_modes] and may be subject to change due to updates.

== Nub Disassembly ==
{{warning|This is a fairly tricky process, and will almost certainly '''void your warranty.'''}}

You need[http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__874378]:
* High quality soldering iron
* Solder Wick
* Shim Blade (Edsyn RB641)
* Isopropyl Alcohol cleaner
* Size 0.00 cross-head screwdriver

Removing the nubs from the PCB is difficult. They are mounted using cut-off plated through holes butted onto pads (fairly standard SMT technology). Just using solder wick will not be sufficient, and if you are not extremely careful, you will rip the pads off the nub or the board.

[[Image:Nub_inside.jpg|thumb|shows the under side of the nub, which has a small PCB screwed on, and 2 locating pins]]

Full sized versions of these photos can be found [http://www.flickr.com/photos/tsh2/4707661640/ here]. Original pics from [http://picasaweb.google.com/claude.schwarz/DropBox?authkey=Gv1sRgCN7KsICXu-KTzwE&feat=directlink Claude], discussion http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__874378 here].

Top left is the micro-joystick which serves as both a spring and the sensing element. when re-assembling this must fit perfectly into the plastic, and be perfectly clean.

==More info on how the nubs work==
Some words from MWeston [http://boards.openpandora.org/index.php?/topic/2270-nubs-feel-weird/page__view__findpost__p__40328 here]: "The nubs were designed to work when thumb pressure is applied. They will not work right if you try to slide them with your finger tip or finger nail or anything like that."

== Early Nub Problems ==
[[Image:Faultynub.jpg | thumb | One example of a faulty nub.]]
The nubs on some of the first units suffered from a myriad of issues. The issues include bad traces, bad resistance in the joystick, looseness, grittiness, nubs not centering, and nubs sticking in one direction.[http://www.openpandora.org/index.php?option=com_content&view=category&layout=blog&id=2&Itemid=2&lang=en] Much of this was caused by the nub manufacturer not having strict enough tolerances[http://www.gp32x.com/board/index.php?/topic/54824-production-status/page__p__883494&#entry883494] and not 'bare board' testing the PCBs used in the manufacture. Probably the most serious problem is that the nubs can break mechanically, resulting in a nub which cannot centre itself. This causes drifting while in-game, rendering the nub completely unusable.

Because of these problems, a few "one nub" units were made available to people who wished to accept one and skip the queue. The faulty nub is not covered under warranty for these units. Reports[http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/] suggest that many of these were reasonably functional, and problems relate to either the calibration process or dirt inside the nub. There is a risk that these nubs might fail with extended use. Soon after the first units were shipped, 100% testing was arranged for the nubs by the supplier and OpenPandora Ltd. (This applies to units shipped after July 27,2010 which are expected to all start with known good nubs)

[[Category:Hardware defects]]
[[Category:Keyboard]]
[[Category:Tutorials]]

Nubs

2013-01-02T03:05:25Z

Porg: /* Nub Configuration */ New nub mode "mbscroll"

The Pandora has 2 analogue controllers 'nubs', which were custom designed.

== Nub Calibration ==
[[Image:Nub_back.jpg|thumb|Backside]]
The nubs need time to calibrate at startup. Often this can be achieved by moving the nubs around once the Pandora has fully loaded (moving them while the OS is still loading may cause a calibration error). Re-calibration of the nubs can be achieved via 'Pandora Menu -> Settings -> Nubs', and selecting either configure <nub> or 'Restore default settings for both nubs'

===Nub Dance===
The 'Nub Dance' or 'Magic Nub Dance' is a technique used to calibrate the Pandora's nubs by exercising the nubs to their hardware limits.

Some of the older nubs required this calibration technique periodically, however newer nubs (since 2011) do not need as much calibration as the older ones.
Push them up, down, left, right to the edge, then let go of them so they spring back by themselves.
i.e. push up, as far as it will go, then let go (it must spring back). Do that for each direction. Then do some circles.
That should set them up. If you don't do this they can go wrong during that session until reset.[http://www.gp32x.com/board/index.php?/topic/54445-please-fix-the-right-anolog-nub-functions/page__view__findpost__p__876651]

===Nub firmware===
The proprietary algorithm for calibrating the nubs is contained within 8KB of flash ROM. More information [http://www.gp32x.com/board/index.php?/topic/53939-the-real-pandora-niche/page__view__findpost__p__865928 here].

===Using compressed air to remove dirt===
If you feel that you might be getting some nub problems caused by dirt having gotten inside, you can try blasting compressed air into the niche where the nubs meet the case. [http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__868440] [http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__871405][http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__872373][http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__872896]

==Nub Configuration==
(As of Zaxxon HF5) 
Nubs can be configured in software under Settings -> Nubs in the Xfce 4 menu system and can also be managed through the filesystem in the /proc/pandora/(nub0/nub1 for left and right nubs respectively).
Most files in that folder (mbutton_threshold, mouse_sensitivity, scroll_rate, scrollx_sensitivity, and scrolly_sensitivity) are fairly straightforward, containing a number determining the value of the attribute.

The only different field is in mode, which contains a string to determine how each nub behaves-

<pre>
mouse - The nub is treated as a mouse, the default configuration of the left nub.
mbuttons - The nub is used as the buttons of the mouse, the default configuration of the right nub.
scroll - The nub scrolls the screen vertically/horizontally as a pair of scroll wheels would.
absolute - The nub is treated as a joystick for the purposes of gaming.
mbscroll* - A combination of mbuttons and scroll. Up/down for scrolling up/down, left/right for according mouse buttons.
</pre>

<nowiki>*</nowiki>'''Note''': As of 2013-01-01 '''mbscroll''' is only available in an experimental kernel image. [http://boards.openpandora.org/index.php/topic/11295-idea-combined-nub-mode-2-mouse-buttons-scrolling-on-1-axis/ Concept by porg], first [http://boards.openpandora.org/index.php/topic/11295-idea-combined-nub-mode-2-mouse-buttons-scrolling-on-1-axis/?p=210868 realization by urjaman] (download & instructions).

The easiest way to alter a nub's mode in the console is to use the following code-
<source lang=bash>
echo "(mode)" > /proc/pandora/nubx/mode
</source>
Where (mode) is one of the above modes and the x in nubx is 0 or 1.

For example, if we wanted to set the left nub to scroll, we'd use
<source lang=bash>
echo "scroll" > /proc/pandora/nub0/mode
</source>
All information pulled from [http://www.pandorawiki.org/PND_nub_modes] and may be subject to change due to updates.

== Nub Disassembly ==
{{warning|This is a fairly tricky process, and will almost certainly '''void your warranty.'''}}

You need[http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__874378]:
* High quality soldering iron
* Solder Wick
* Shim Blade (Edsyn RB641)
* Isopropyl Alcohol cleaner
* Size 0.00 cross-head screwdriver

Removing the nubs from the PCB is difficult. They are mounted using cut-off plated through holes butted onto pads (fairly standard SMT technology). Just using solder wick will not be sufficient, and if you are not extremely careful, you will rip the pads off the nub or the board.

[[Image:Nub_inside.jpg|thumb|shows the under side of the nub, which has a small PCB screwed on, and 2 locating pins]]

Full sized versions of these photos can be found [http://www.flickr.com/photos/tsh2/4707661640/ here]. Original pics from [http://picasaweb.google.com/claude.schwarz/DropBox?authkey=Gv1sRgCN7KsICXu-KTzwE&feat=directlink Claude], discussion http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/page__view__findpost__p__874378 here].

Top left is the micro-joystick which serves as both a spring and the sensing element. when re-assembling this must fit perfectly into the plastic, and be perfectly clean.

==More info on how the nubs work==
Some words from MWeston [http://boards.openpandora.org/index.php?/topic/2270-nubs-feel-weird/page__view__findpost__p__40328 here]: "The nubs were designed to work when thumb pressure is applied. They will not work right if you try to slide them with your finger tip or finger nail or anything like that."

== Early Nub Problems ==
[[Image:Faultynub.jpg | thumb | One example of a faulty nub.]]
The nubs on some of the first units suffered from a myriad of issues. The issues include bad traces, bad resistance in the joystick, looseness, grittiness, nubs not centering, and nubs sticking in one direction.[http://www.openpandora.org/index.php?option=com_content&view=category&layout=blog&id=2&Itemid=2&lang=en] Much of this was caused by the nub manufacturer not having strict enough tolerances[http://www.gp32x.com/board/index.php?/topic/54824-production-status/page__p__883494&#entry883494] and not 'bare board' testing the PCBs used in the manufacture. Probably the most serious problem is that the nubs can break mechanically, resulting in a nub which cannot centre itself. This causes drifting while in-game, rendering the nub completely unusable.

Because of these problems, a few "one nub" units were made available to people who wished to accept one and skip the queue. The faulty nub is not covered under warranty for these units. Reports[http://www.gp32x.com/board/index.php?/topic/54073-the-one-nub-club/] suggest that many of these were reasonably functional, and problems relate to either the calibration process or dirt inside the nub. There is a risk that these nubs might fail with extended use. Soon after the first units were shipped, 100% testing was arranged for the nubs by the supplier and OpenPandora Ltd. (This applies to units shipped after July 27,2010 which are expected to all start with known good nubs)

[[Category:Hardware defects]]
[[Category:Keyboard]]
[[Category:Tutorials]]

PND management workflow

2012-08-23T15:03:50Z

Porg: /* Whom it concerns */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, Hotkey / text-based launchers
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T15:02:53Z

Porg: /* Whom it concerns */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers ("hotkey > insert a few characters > get matching apps", see: [[#Hotkey application launcher]])
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T15:00:20Z

Porg: /* Launch */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this, there are some suggestions for improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:58:22Z

Porg: /* Mass OVR editor */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed [http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/ OVR editor], and considers to realize the fore-mentioned "OVR spreadsheet editing mode".

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:56:21Z

Porg: /* MiniMenu - Test an app, quit it, tag it */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

* Issue 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
* Issue 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

UPDATE: Issue 1 + 2 got fixed, thus the method "test an app, quit it, tag it" practically works in MiniMenu.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:53:28Z

Porg: /* Install/update/remove */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to aid in the "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:50:47Z

Porg: /* Discover */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "discover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to facilitate "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:50:11Z

Porg: /* Discover */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). These media especially increase the chances for newcomers, which are yet not so informed. If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "disover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to facilitate "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:42:47Z

Porg: /* Follow up */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment with a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the forum thread please), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). This medias especially increase the chances for newcomers, which are yet un-featured in the information and informal medias! If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "disover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to facilitate "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PND management workflow

2012-08-23T14:41:03Z

Porg: /* Whom it concerns */

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, text based launchers (hotkey > insert a few characters > get matching apps)
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment without a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the thread as this is "meta"), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). This medias especially increase the chances for newcomers, which are yet un-featured in the information and informal medias! If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "disover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to facilitate "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

PXML specification

2012-04-29T22:03:05Z

Porg: /* The element */

This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]].

'''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. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.

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.

The following specification is based on what the latest version of the PXML_schema.xsd definition accepts as valid data. Files that do not pass the validation might still work as expected, but if the validation is passed you can be (almost) 100% sure that it is supposed to be correct.

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

== General 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">

</PXML>
</source>

As you can see, the PXML tag only requires the "xmlns" attribute.

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

=== The <package> element ===
Since "pnd"-files can contain various applications the new <package> element was introduced. It is meant to allow you to describe what the package is about. This will, at least at the moment (firmware 1 pre hotfix6), not be used by the pandora itself for detection, but is meant as tool for package repositories as well as package managers that might eventually be created. Each pnd should have one of those at the top (and only one). The information required in the <package> block will be explained below in the respective section below.

=== The <application> element ===
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. The information required in the <application> blocks will be explained below in the respective section below.

== The <package> area ==
As described above, each pnd should start with a package description. For single application packages this can basically be a copy of the respective areas from the <application> element.

<source lang="xml">
<package id="uniqueID">

</package>
</source>

* ''(required)'' The "id" attribute specifies an identifier common to all versions of a particular PND package. This can be achieved by appending some random number to your package name or by simply generating a completely random, very long identifier. A good ID may consist of the application name, developer name and some key, for example ''battlejewels.skeezix.001'' or ''quake-1.pickle.001''. '''The package ID must not include characters which would be invalid in directory or file names, such as ?, >, /, etc. Use of such characters will prevent the PND from functioning.''' The package ID allows repositories to identify different versions of the same package and therefore determine whether that package should be updated. The package ID should therefore '''not''' be changed if a package is merely updated.

=== The <author> element ===
==== Description ====
The author element is an element that is used by the author to introduce him/herself.
An author element is mandatory. It accepts the following attributes:

* ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The website attribute specifies the website of the author.
* ''(optional)'' The email attribute specifies the e-mail of the author.

==== 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 is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

* ''(required)'' The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(optional'' You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2" type="release"/>
</source>

=== The <titles> element ===
==== Description ====
The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

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

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

=== The <descriptions> element ===
==== Description ====
The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. Additional tags are optional. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

==== Example ====
<source lang="xml">
<descriptions>
<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>
</descriptions>
</source>

=== The <icon> element ===
==== Description ====
The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

* ''(required)'' 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 <application> area ==
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>

* ''(required)'' The "id" attribute specifies an identifier for your current application, 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.

* ''(optional)'' 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.
'''Notice: appdata names with dashes in (e.g. quake-2 rather than quake2) will cause the pnd file to function improperly.'''

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.

Below are the allowed elements inside the <application> blocks. You can have as many applications listed in a single PXML file as you want to (though there is/was a limit in libpnd that was set to about 50 once upon the time, which might eventually be completely be removed).

=== 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. Only exactly one exec element is allowed. It accepts the following attributes:

* ''(required)'' 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.
* ''(optional)'' The arguments attribute may be not present, or present with 1 or more arguments to the executable.
* ''(optional)'' 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.
* ''(optional)'' 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).
* ''(optional)'' 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.
* ''(optional)'' 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 <author> element ===
==== Description ====
The author element is an element that is used by the author to introduce him/herself.
An author element is mandatory. It accepts the following attributes:

* ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The website attribute specifies the website of the author.
* ''(optional)'' The email attribute specifies the e-mail of the author.

==== 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 is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

* ''(required)'' The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(optional'' You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2" type="release"/>
</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. If unsure, just use a '0' in the respective field.

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

* ''(required)'' The major attribute specifies the major version number. Valid entries: non negative integers.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: non negative integers.
* ''(required)'' The release attribute specifies the release number. Valid entries: non negative integers.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: non negative integers.

=== The <titles> element ===
==== Description ====
The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the application title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

'''Note:''' This is new in HF6. For backwards compatibilty please include the <title lang="en_US"> once outside the <titles> block, too!

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

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

=== The <descriptions> element ===
==== Description ====
The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

'''Note:''' This is new in HF6. For backwards compatibilty please include the <description lang="en_US"> once outside the <titles> block, too!

==== Example ====
<source lang="xml">
<descriptions>
<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>
</descriptions>
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
</source>

=== The <icon> element ===
==== Description ====
The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

* ''(required)'' 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 <licenses> element ===
==== Description ====
The licenses element is an element that contains multiple other elements.

It contains multiple license elements. Every element represents one license (so you *can* also multilicense something). You have to provide at least one license for your application. You can basically enter anything you want, though if you are using an existing license, it is best to just enter the name and provide a link to the full version. This tag also allows you to provide links to websites with the sourcecode.

* ''(required)'' The name attribute specifies what the license is called. If you don't have a real license you can also enter some short text here (please keep it short!) or just enter "other" and doN't care no more.
* ''(optional)'' The url attribute can be used to specify a url to the full license text.
* ''(optional)'' The sourcecodeurl attribute can be used to specify a url to the sources.

==== Example ====
<source lang="xml">
<licenses>
<license name="GPLv2+" url="http://www.gnu.org/licenses/gpl-2.0.html" sourcecodeurl="http://pandora.org/sources/package.tar.bz2"/>
<license name="other"/>
</licenses>
</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. Use the native 800x480 LCD screen resolution, minimenu and others will scale it down as needed.

* ''(required)'' The src attribute on a pic element specifies the path to the image file used as the preview picture.

==== Recommendation ====

If you define multiple <previewpic> elements, then set the most illustrative picture as the primary <previewpic>! 
''Why?'' Because many context use only that picture at all or at that picture at first sight and more only on demand. ''Examples:''
* [[Minimenu]]'s preview function (toggled via "A") shows only the first picture,
* [http://repo.openpandora.org/includes/rss.php Repo RSS feed] shows only the first picture,
* [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager]'s app info shows 1 picture at first sight, more on demand.

Currently there is no technical definition of the ''"primary"'' <previewpic>, therefore ensure that your intended primary <previewpic>
* occurs first in the source code order,
* has a filename that lists it first in a typical lexicographical sorting order.

''What is an illustrative picture?'' 
It should quickly give an impression of the look & feel of an application. 
I.e. for video games this would mean and in-game screenshot rather than a main menu screenshot, except if the menu is just a small overlay, and the important parts of the game can still be seen.

[http://boards.openpandora.org/index.php?/topic/8137-pnd-packagers-1-please-provide-previewpics-2-define-primary-pic-if-you-give-multiple/ Discussion in the developer forum]

==== Example ====
<source lang="xml">
<previewpics>
<pic src="preview/pic1.jpg"/>
<pic src="preview/pic2.jpg"/>
</previewpics>
</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. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

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!

* ''(required)'' 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".
* ''(required)'' 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). Those two are the only types allowed if the validation against the scheme is meant to be successful.
* ''(required)'' src → 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 <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.

For passing validation any category/subcategory entries have to confirm to the FDO specs linked above.

==== 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 ====
'''This element is not integrated into the firmware (Release Zaxxon) yet - therefore using it will have no effect!'''

The associations element is an element that contains multiple other elements.
An associations element is optional, except if exec.standalone is false (this is not checked via the schema!).

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

* ''(required)'' The name attribute on an association element specifies the user-friendly action name for the association.
* ''(required)'' The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.
* ''(required)'' 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:

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

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

== Example files ==
There are several example files available in the [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=tree;f=docs/examples git repository]. They do match the current specification and (unless mentioned differently) validate. Below the direct links and a short description what they are meant to show:

* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/average-case_PXML.xml average-case_PXML.xml]: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/full-sample_PXML.xml full-sample_PXML.xml]: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-schema_PXML.xml minimum-schema_PXML.xml]: This is a minimum example that will validate with the schema but basically offer nothing beside what really is required. This application should work nicely with any pnd repositories based upon the PXML specs. '''NOTE:''' This application will not work with pre HF6, for support for OS versions up to HF6 an additional <title> block outside of <titles> is required!
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-libpnd_PXML.xml minimum-libpnd_PXML.xml]: This is a minimum example that will work on the pandora, but is '''not''' following the schema and lots of information that will be required for repositories based on the PXML specs is not available.

== Validation ==
To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it. The schema is also available in a plaintext file described in words that are by far more compact than this page but still understandable for coders: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/PXML_schema_plaintext.txt plaintext description of the schema]

The current-most XSD is in 'libpnd' (in the git repository). Here is the file history: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=history;f=docs/PXML_schema.xsd PXML_schema.xsd file history]
Once on the history page, just click on the filename (right click -> save as) to download the latest version.

The easiest way to run validation is using this command:
xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml
To run it you have to have xmllint installed and the (latest) PXML_schema.xsd definition downloaded. Using this command you can now simply evaluate if the PXML.xml file is valid. xmllint can be installed via the angstrom repository (it is part of libxml2-utils).

'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for '''' and include those blocks in your pxml file.

[[Category:Development]]
[[Category:Official OpenPandora Development]]
[[Category:PND]]

PXML specification

2012-04-29T16:18:52Z

Porg: /* The element */ Recommending to define a primary <previewpic> among multiple pictures

This article covers the specification for PXML files. To see the specification for PND repository files, please see the [[PND repository specification]].

'''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. In general it is likely that a working PXML file will stay valid, if the schema definition mentioned here is followed.

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.

The following specification is based on what the latest version of the PXML_schema.xsd definition accepts as valid data. Files that do not pass the validation might still work as expected, but if the validation is passed you can be (almost) 100% sure that it is supposed to be correct.

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

== General 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">

</PXML>
</source>

As you can see, the PXML tag only requires the "xmlns" attribute.

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

=== The <package> element ===
Since "pnd"-files can contain various applications the new <package> element was introduced. It is meant to allow you to describe what the package is about. This will, at least at the moment (firmware 1 pre hotfix6), not be used by the pandora itself for detection, but is meant as tool for package repositories as well as package managers that might eventually be created. Each pnd should have one of those at the top (and only one). The information required in the <package> block will be explained below in the respective section below.

=== The <application> element ===
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. The information required in the <application> blocks will be explained below in the respective section below.

== The <package> area ==
As described above, each pnd should start with a package description. For single application packages this can basically be a copy of the respective areas from the <application> element.

<source lang="xml">
<package id="uniqueID">

</package>
</source>

* ''(required)'' The "id" attribute specifies an identifier common to all versions of a particular PND package. This can be achieved by appending some random number to your package name or by simply generating a completely random, very long identifier. A good ID may consist of the application name, developer name and some key, for example ''battlejewels.skeezix.001'' or ''quake-1.pickle.001''. '''The package ID must not include characters which would be invalid in directory or file names, such as ?, >, /, etc. Use of such characters will prevent the PND from functioning.''' The package ID allows repositories to identify different versions of the same package and therefore determine whether that package should be updated. The package ID should therefore '''not''' be changed if a package is merely updated.

=== The <author> element ===
==== Description ====
The author element is an element that is used by the author to introduce him/herself.
An author element is mandatory. It accepts the following attributes:

* ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The website attribute specifies the website of the author.
* ''(optional)'' The email attribute specifies the e-mail of the author.

==== 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 is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

* ''(required)'' The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(optional'' You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2" type="release"/>
</source>

=== The <titles> element ===
==== Description ====
The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the package title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

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

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

=== The <descriptions> element ===
==== Description ====
The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. Additional tags are optional. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

==== Example ====
<source lang="xml">
<descriptions>
<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>
</descriptions>
</source>

=== The <icon> element ===
==== Description ====
The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

* ''(required)'' 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 <application> area ==
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>

* ''(required)'' The "id" attribute specifies an identifier for your current application, 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.

* ''(optional)'' 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.
'''Notice: appdata names with dashes in (e.g. quake-2 rather than quake2) will cause the pnd file to function improperly.'''

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.

Below are the allowed elements inside the <application> blocks. You can have as many applications listed in a single PXML file as you want to (though there is/was a limit in libpnd that was set to about 50 once upon the time, which might eventually be completely be removed).

=== 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. Only exactly one exec element is allowed. It accepts the following attributes:

* ''(required)'' 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.
* ''(optional)'' The arguments attribute may be not present, or present with 1 or more arguments to the executable.
* ''(optional)'' 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.
* ''(optional)'' 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).
* ''(optional)'' 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.
* ''(optional)'' 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 <author> element ===
==== Description ====
The author element is an element that is used by the author to introduce him/herself.
An author element is mandatory. It accepts the following attributes:

* ''(required)'' The name attribute specifies the name of the author.
* ''(optional)'' The website attribute specifies the website of the author.
* ''(optional)'' The email attribute specifies the e-mail of the author.

==== 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 is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the following attributes:

* ''(required)'' The major attribute specifies the major version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The release attribute specifies the release number. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: strings consisting of letters (a-z and A-Z) as well as the chars '+' and '-'.
* ''(optional'' You can specify a type attribute that is either set to "release", "beta" or "alpha". This will (at the moment) not be read by libpnd but package repositories might use it in some way (to eg mark "beta" versions explicitly or something like this). If this is not specified, "release" will be assumed.

==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2" type="release"/>
</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. If unsure, just use a '0' in the respective field.

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

* ''(required)'' The major attribute specifies the major version number. Valid entries: non negative integers.
* ''(required)'' The minor attribute specifies the minor version number. Valid entries: non negative integers.
* ''(required)'' The release attribute specifies the release number. Valid entries: non negative integers.
* ''(required)'' The build attribute specifies what build the application is at. Valid entries: non negative integers.

=== The <titles> element ===
==== Description ====
The titles element is an element that contains multiple other elements.

The titles element specifies the text that is shown to the users of your PND file as the application title. Inside the <titles> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The <titles> element with at least one "title"-element is required, in the "en_US" American English language. Additional tags are optional.

'''Note:''' This is new in HF6. For backwards compatibilty please include the <title lang="en_US"> once outside the <titles> block, too!

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

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

=== The <descriptions> element ===
==== Description ====
The descriptions element is an element that contains multiple other elements.

The descriptions element specifies the text that is shown to the users of your PND file as the package description. Inside the <descriptions> block should be one entry for each language you want to support. The first language listed should always be ''en_US''. The language is indicated by the lang attribute. The "descriptions"-element is optional, though it is highly recommended to specify it. If specified, at least one entry for "en_US" ( American English language) is required. Several of those elements are allowed, one for each lang that you want to display.

'''Note:''' This is new in HF6. For backwards compatibilty please include the <description lang="en_US"> once outside the <titles> block, too!

==== Example ====
<source lang="xml">
<descriptions>
<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>
</descriptions>
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
</source>

=== The <icon> element ===
==== Description ====
The icon element should specify a nice icon for your application. An icon element is optional, but if one is specified you have to include the src attribute. Only up to one icon element is allowed. It accepts the following attributes:

* ''(required)'' 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 <licenses> element ===
==== Description ====
The licenses element is an element that contains multiple other elements.

It contains multiple license elements. Every element represents one license (so you *can* also multilicense something). You have to provide at least one license for your application. You can basically enter anything you want, though if you are using an existing license, it is best to just enter the name and provide a link to the full version. This tag also allows you to provide links to websites with the sourcecode.

* ''(required)'' The name attribute specifies what the license is called. If you don't have a real license you can also enter some short text here (please keep it short!) or just enter "other" and doN't care no more.
* ''(optional)'' The url attribute can be used to specify a url to the full license text.
* ''(optional)'' The sourcecodeurl attribute can be used to specify a url to the sources.

==== Example ====
<source lang="xml">
<licenses>
<license name="GPLv2+" url="http://www.gnu.org/licenses/gpl-2.0.html" sourcecodeurl="http://pandora.org/sources/package.tar.bz2"/>
<license name="other"/>
</licenses>
</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. Use the native 800x480 LCD screen resolution, minimenu and others will scale it down as needed.

* ''(required)'' The src attribute on a pic element specifies the path to the image file used as the preview picture.

==== Recommendation ====

If you define multiple <previewpic> elements, then set the most illustrative picture as the primary <previewpic>! 
''Why?'' Because many context use only that picture at all or at that picture at first sight and more only on demand. ''Examples:''
* [[Minimenu]]'s preview function (toggled via "A") shows only the first picture,
* [http://repo.openpandora.org/includes/rss.php Repo RSS feed] shows only the first picture,
* [http://repo.openpandora.org/?page=detail&app=pndmanager-bzar PNDManager]'s app info shows 1 picture at first sight, more on demand.

Currently there is no technical definition of the ''"primary"'' <previewpic>, therefore ensure that your intended primary <previewpic>
* occurs first in the source code order,
* has a filename that lists it first in a typical lexicographical sorting order.

''What is an illustrative picture?''

It should quickly give an impression of the look & feel of an application.

I.e. for video games this would mean and in-game screenshot rather than a main menu screenshot, except if the menu is just a small overlay, and the important parts of the game can still be seen.

==== Example ====
<source lang="xml">
<previewpics>
<pic src="preview/pic1.jpg"/>
<pic src="preview/pic2.jpg"/>
</previewpics>
</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. Per application only up to one of those entries is allowed. If you need more, the best approach is to create an html file and link the other files.

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!

* ''(required)'' 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".
* ''(required)'' 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). Those two are the only types allowed if the validation against the scheme is meant to be successful.
* ''(required)'' src → 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 <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.

For passing validation any category/subcategory entries have to confirm to the FDO specs linked above.

==== 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 ====
'''This element is not integrated into the firmware (Release Zaxxon) yet - therefore using it will have no effect!'''

The associations element is an element that contains multiple other elements.
An associations element is optional, except if exec.standalone is false (this is not checked via the schema!).

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

* ''(required)'' The name attribute on an association element specifies the user-friendly action name for the association.
* ''(required)'' The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.
* ''(required)'' 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:

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

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

== Example files ==
There are several example files available in the [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=tree;f=docs/examples git repository]. They do match the current specification and (unless mentioned differently) validate. Below the direct links and a short description what they are meant to show:

* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/PXML.xml PXML.xml]: This is a sample PXML.xml file making use of many different things.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/average-case_PXML.xml average-case_PXML.xml]: This is an example how a "common" pnd with just one application could look. Most of the information for the <package> block can in this case directly be copied over from the respective parts in the <application> block.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/full-sample_PXML.xml full-sample_PXML.xml]: This is a complex example defining a "real" package collection. It offers several applications, all using different features of PXML.
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-schema_PXML.xml minimum-schema_PXML.xml]: This is a minimum example that will validate with the schema but basically offer nothing beside what really is required. This application should work nicely with any pnd repositories based upon the PXML specs. '''NOTE:''' This application will not work with pre HF6, for support for OS versions up to HF6 an additional <title> block outside of <titles> is required!
* [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/examples/minimum-libpnd_PXML.xml minimum-libpnd_PXML.xml]: This is a minimum example that will work on the pandora, but is '''not''' following the schema and lots of information that will be required for repositories based on the PXML specs is not available.

== Validation ==
To validate a PXML file, you need a XSD (XML schema) validator, and you have to know how to use it. The schema is also available in a plaintext file described in words that are by far more compact than this page but still understandable for coders: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=blob;f=docs/PXML_schema_plaintext.txt plaintext description of the schema]

The current-most XSD is in 'libpnd' (in the git repository). Here is the file history: [http://git.openpandora.org/cgi-bin/gitweb.cgi?p=pandora-libraries.git;a=history;f=docs/PXML_schema.xsd PXML_schema.xsd file history]
Once on the history page, just click on the filename (right click -> save as) to download the latest version.

The easiest way to run validation is using this command:
xmllint --noout --schema PATH/TO/PXML_schema.xsd PATH/TO/PXML.xml
To run it you have to have xmllint installed and the (latest) PXML_schema.xsd definition downloaded. Using this command you can now simply evaluate if the PXML.xml file is valid. xmllint can be installed via the angstrom repository (it is part of libxml2-utils).

'''Attention''': It is possible to validate PXML files that won't work with pre HotFix6. If you want to have the pnd work with basically all versions of the OS (you most likely want this!) please have a look above searching for '''' and include those blocks in your pxml file.

[[Category:Development]]
[[Category:Official OpenPandora Development]]
[[Category:PND]]

Power modes

2012-04-08T21:43:39Z

Porg: /* Times */

[[Image:Battery.jpg|thumb|The Pandora's battery]]

==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. Note that as of [[hotfix3]], opening the lid in low power mode has no effect.

===Normal Mode===
This is the normal operating mode, [[display]] on, [[WiFi]] and [[Bluetooth]] on if requested. [[CPU speed]] can be selected by the user, and has a small impact on battery life. Screen brightness will also have a significant effect on battery life. The CPU should automatically self-regulate to the current task, and 10-14 hours [[battery]] life is possible depending on usage. This is mostly independent of the set CPU speed for any given task. At any time, the battery gauge will show the remaining battery life ''if the usage remains the same as over the past some seconds''.

===Lid Closed===
The only change with the lid closed is to turn off the LCD [[backlight]]. This improves battery life, allowing music playback and streaming to continue. As of [[Hotfix2]], the screen remains on if the device is powered up with the screen closed. It is also possible to set [[xfce]] to blank the screen after a period of inactivity, which helps with battery.

===Low Power===
Low power mode is toggled by a short press of the [[power switch]] to the right. The screen is off, the [[radios]] are disabled, the CPU max speed is set to 14 MHz. The device is still silently on, allowing for alarms to go off or it to be turned on again instantly. The power [[LED]] will be dimmed, and may appear to be off if you are outside.

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 days or longer.

Since the Pandora has to be powered whilst it is charging, low power mode is best for fastest charging, and will even allow a full charge to be achieved from [[USB]]. It is also the best way to use the Pandora as a [[USB]] charger for other devices.

Opening the [[screen]] whilst in low power mode has no effect (screen stays off, clocks stay low), and you will need to use the power switch to resume.

At the moment, there is no clear advantage in slowing the clocks (other than being an effective pause button when playing MP3). The only saving is through disabling the radios. This is likely to be improved in due course since there are features in the omap processor for power saving which are being added to the linux [[kernel]].

===Power Off===
Select Logout then Shutdown from the window manager to power off. If a charger is connected, the device will re-boot immediately. It is possible to get into a state where you believe it is powered off, but in fact it is using power at the normal screen off rate - so after 12 hours, 50% of your battery is gone. The Power green [[LED]] ought to be a tell-tale. It is possible that some bugs exist in this area, but nothing has been clearly identified[http://www.gp32x.com/board/index.php?/topic/54652-solved-pandora-lost-charge-overnight/]

A common problem seems to be that if you switch off ''before'' unplugging, your Pandora will re-boot even though it is now left unplugged. This problem is compounded by the low battery shutdown script being called repeatedly (and actually preventing shutdown).

To do a '''hard-reset''' of the Pandora (in case of software crashes), press and hold the [[Pandora key]] and flick the power button to the right.

To do a '''hard-shutdown''' of the Pandora, press and hold the Pandora key ''with right shoulder button held'' and flick the power button to the right, and then select shutdown from the menu.[http://www.gp32x.com/board/index.php?/topic/59233-hf5-not-shutting-down-or-rebooting/page__view__findpost__p__946375]

There is also a "secret" reset method if the above doesn't work, described [http://boards.openpandora.org/index.php?/topic/520-flashing-failure-now-the-board-would-not-power-up/page__p__8594#entry8594 here].

==Events==
The events which control power can be customised [http://www.gp32x.com/board/index.php?/topic/54544-forcing-shutdown-at-10-battery-life/page__view__findpost__p__878418]. Lid switch, Power Switch, battery threshold and Window Manager shutdown commands. Note that the battery manager in xfce will also take action when the battery is low, by default forcing a shutdown at 5% (so you may observe a full boot process, the window manager appears, then immediately shuts down)

==Charging==
[[image:Power_uk.png|thumb|alt=UK charger and adapter|UK charger and adapter]]
It is possible to charge from the mains charger (use the supplied one or a ''GENUINE'' PSP adaptor only) or [[USB]] cable. While a charger is connected, remaining [[battery]] level is displayed, but the time displays 00:00. If charging from USB, it is possible that the battery will still discharge slowly, since the Pandora takes more current (in normal mode) than the USB can supply. Mains charge is configured to draw 1000mA, USB charge is more like 500mA.

It is not possible to charge the Pandora without turning it on - the charging circuits rely on the CPU for configuration. In practice, this has minimal impact on usage, except that after charging, you might wish to explicitly turn off (and maybe there is a easy way to automate this by adding a charger event to call a script)

If your Pandora's [[battery]] is at less than 1% (actually configurable in [[XFCE]]), then you may have problems in using [[USB]] to charge the Pandora. Currently, [[USB]] is not recognised by the [[XFCE]] battery monitor so it will shutdown with no warning. As a workaround, you can put your Pandora into low power mode as soon as the flashing mouse icon (XFE startup) appears. This should significantly delay loading the battery monitor widget, and even if the charge hasn't passed 1% by the time it checks, on the next try you should be there.

==Operating Point==
The ''OPP'' is a TI term which reflects the fact that low clock speeds can be achieved with lower supply voltage than the higher clock speeds. Increasing OPP will reduce the lifetime of the device significantly (from 10 years to 5 years of continuous use.) OPP3 is the default as shipped by OpenPandora. As of Hotfix4, it is possible to set a maximum OPP in the range 1-5 (for example, to 5):
<source lang="bash">echo 5 | sudo tee -a /proc/pandora/cpu_opp_max</source>
This will then increase OPP to suit the requested CPU max, as pre-determined by a table built in to the kernel. These thresholds use OPP1 for below 125 MHz, and OPP5 for above 720 MHz. It is possible to set the limiter and maybe run at 500 MHz in OPP2 (depending on your specific chip). See [http://boards.openpandora.org/index.php?/topic/22-using-hotfix4-how-high-can-you-clock/ this forum thread] for actual results.

{{warning
|Using anything above OPP3 WILL shorten the lifetime of your Pandora, although it should still outlive the 1 year warranty. Using anything above OPP5 and 1Ghz will void your warranty (see [[Overclocking#Warranty_information|here]])
}}

Tweaking scripts to make this tuning easier are in the works.

==Monitoring==
The [[kernel]] provides some information about battery state through the filesystem. See [[Data_provided_by_Battery_and_Power_driver]]. This may help with diagnosing problems.

==Times==
* This data originates from different studies performed under different OS versions and use cases.
* Please add the source and a short note about the conditions you used, and if necessary more detailed ones to the Talk page.
{| class="wikitable"
!Mode
!Time
!Details, Source
|-
! Active PND applications
| 10-20 hours
| OS SuperZaxxon, Beta 2, Kernel 3.2.1
|-
! MP3 play, screen off
| 43 hours
| MP3 playback in [http://repo.openpandora.org/?page=detail&app=audacious Audacious] in [http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 OS SuperZaxxon, Beta 2, Kernel 3.2.1]
|
|-
! Low Power Mode
|30-75 hours
| [http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 OS SuperZaxxon, Beta 2, Kernel 3.2.1]
|-
! Standby Mode
| 160-200 hours
| [http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 OS SuperZaxxon, Beta 2, Kernel 3.2.1]
|-
! Power off
|5% charge loss per week
| although there are reports of much faster drain?[http://boards.openpandora.org/index.php?/topic/24-battery-drain/]
|-
! Mains charge, operating
| 20 hours
| estimate, OS Zaxxon, Hotfix 3
|-
! Mains charge (low power)
|8 hours
| estimate, OS Zaxxon, Hotfix 3
|-
! USB Charge, operating
| 20 hours
| inactive, screen+wifi on, may charge or discharge depending on load
|-
! USB Charge, low power
|20 hours
|estimate
|}

==Battery Care==
* You can charge your [[battery]] to full charge, the charging circuits will then reduce the current to avoid overheating
* If you won't use the [[battery]] for more than a week, it is best to leave it at about 40% charged (as opposed to full)
* Don't worry about running it down too low, there are protection circuits to avoid a '''damagingly low discharge'''.
**Avoid leaving the battery completely discharged though. When the power runs out, the system will be unable to shutdown cleanly, and might corrupt your files or the system.
* No harm will come if you only partially recharge it. If you've only got 10 free minutes to charge before leaving, go ahead. You'll put an hour of usage back into the battery, and you can always charge it more later.
* For best accuracy, the battery meter relies on watching the battery discharge over most of it's range (down to say 10%).
**This will only affect the 'time to run' indication
* If you're not going to be using your battery for a very long time, the extremely best thing you can do for it is to discharge to 40%, seal it in an airtight bag, and put it in the fridge. Even years later, you pull it out, and it will be almost as good as when you put it in.

[[Category:Power supply]]

Power modes

2012-04-08T21:40:55Z

Porg: /* Times */

[[Image:Battery.jpg|thumb|The Pandora's battery]]

==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. Note that as of [[hotfix3]], opening the lid in low power mode has no effect.

===Normal Mode===
This is the normal operating mode, [[display]] on, [[WiFi]] and [[Bluetooth]] on if requested. [[CPU speed]] can be selected by the user, and has a small impact on battery life. Screen brightness will also have a significant effect on battery life. The CPU should automatically self-regulate to the current task, and 10-14 hours [[battery]] life is possible depending on usage. This is mostly independent of the set CPU speed for any given task. At any time, the battery gauge will show the remaining battery life ''if the usage remains the same as over the past some seconds''.

===Lid Closed===
The only change with the lid closed is to turn off the LCD [[backlight]]. This improves battery life, allowing music playback and streaming to continue. As of [[Hotfix2]], the screen remains on if the device is powered up with the screen closed. It is also possible to set [[xfce]] to blank the screen after a period of inactivity, which helps with battery.

===Low Power===
Low power mode is toggled by a short press of the [[power switch]] to the right. The screen is off, the [[radios]] are disabled, the CPU max speed is set to 14 MHz. The device is still silently on, allowing for alarms to go off or it to be turned on again instantly. The power [[LED]] will be dimmed, and may appear to be off if you are outside.

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 days or longer.

Since the Pandora has to be powered whilst it is charging, low power mode is best for fastest charging, and will even allow a full charge to be achieved from [[USB]]. It is also the best way to use the Pandora as a [[USB]] charger for other devices.

Opening the [[screen]] whilst in low power mode has no effect (screen stays off, clocks stay low), and you will need to use the power switch to resume.

At the moment, there is no clear advantage in slowing the clocks (other than being an effective pause button when playing MP3). The only saving is through disabling the radios. This is likely to be improved in due course since there are features in the omap processor for power saving which are being added to the linux [[kernel]].

===Power Off===
Select Logout then Shutdown from the window manager to power off. If a charger is connected, the device will re-boot immediately. It is possible to get into a state where you believe it is powered off, but in fact it is using power at the normal screen off rate - so after 12 hours, 50% of your battery is gone. The Power green [[LED]] ought to be a tell-tale. It is possible that some bugs exist in this area, but nothing has been clearly identified[http://www.gp32x.com/board/index.php?/topic/54652-solved-pandora-lost-charge-overnight/]

A common problem seems to be that if you switch off ''before'' unplugging, your Pandora will re-boot even though it is now left unplugged. This problem is compounded by the low battery shutdown script being called repeatedly (and actually preventing shutdown).

To do a '''hard-reset''' of the Pandora (in case of software crashes), press and hold the [[Pandora key]] and flick the power button to the right.

To do a '''hard-shutdown''' of the Pandora, press and hold the Pandora key ''with right shoulder button held'' and flick the power button to the right, and then select shutdown from the menu.[http://www.gp32x.com/board/index.php?/topic/59233-hf5-not-shutting-down-or-rebooting/page__view__findpost__p__946375]

There is also a "secret" reset method if the above doesn't work, described [http://boards.openpandora.org/index.php?/topic/520-flashing-failure-now-the-board-would-not-power-up/page__p__8594#entry8594 here].

==Events==
The events which control power can be customised [http://www.gp32x.com/board/index.php?/topic/54544-forcing-shutdown-at-10-battery-life/page__view__findpost__p__878418]. Lid switch, Power Switch, battery threshold and Window Manager shutdown commands. Note that the battery manager in xfce will also take action when the battery is low, by default forcing a shutdown at 5% (so you may observe a full boot process, the window manager appears, then immediately shuts down)

==Charging==
[[image:Power_uk.png|thumb|alt=UK charger and adapter|UK charger and adapter]]
It is possible to charge from the mains charger (use the supplied one or a ''GENUINE'' PSP adaptor only) or [[USB]] cable. While a charger is connected, remaining [[battery]] level is displayed, but the time displays 00:00. If charging from USB, it is possible that the battery will still discharge slowly, since the Pandora takes more current (in normal mode) than the USB can supply. Mains charge is configured to draw 1000mA, USB charge is more like 500mA.

It is not possible to charge the Pandora without turning it on - the charging circuits rely on the CPU for configuration. In practice, this has minimal impact on usage, except that after charging, you might wish to explicitly turn off (and maybe there is a easy way to automate this by adding a charger event to call a script)

If your Pandora's [[battery]] is at less than 1% (actually configurable in [[XFCE]]), then you may have problems in using [[USB]] to charge the Pandora. Currently, [[USB]] is not recognised by the [[XFCE]] battery monitor so it will shutdown with no warning. As a workaround, you can put your Pandora into low power mode as soon as the flashing mouse icon (XFE startup) appears. This should significantly delay loading the battery monitor widget, and even if the charge hasn't passed 1% by the time it checks, on the next try you should be there.

==Operating Point==
The ''OPP'' is a TI term which reflects the fact that low clock speeds can be achieved with lower supply voltage than the higher clock speeds. Increasing OPP will reduce the lifetime of the device significantly (from 10 years to 5 years of continuous use.) OPP3 is the default as shipped by OpenPandora. As of Hotfix4, it is possible to set a maximum OPP in the range 1-5 (for example, to 5):
<source lang="bash">echo 5 | sudo tee -a /proc/pandora/cpu_opp_max</source>
This will then increase OPP to suit the requested CPU max, as pre-determined by a table built in to the kernel. These thresholds use OPP1 for below 125 MHz, and OPP5 for above 720 MHz. It is possible to set the limiter and maybe run at 500 MHz in OPP2 (depending on your specific chip). See [http://boards.openpandora.org/index.php?/topic/22-using-hotfix4-how-high-can-you-clock/ this forum thread] for actual results.

{{warning
|Using anything above OPP3 WILL shorten the lifetime of your Pandora, although it should still outlive the 1 year warranty. Using anything above OPP5 and 1Ghz will void your warranty (see [[Overclocking#Warranty_information|here]])
}}

Tweaking scripts to make this tuning easier are in the works.

==Monitoring==
The [[kernel]] provides some information about battery state through the filesystem. See [[Data_provided_by_Battery_and_Power_driver]]. This may help with diagnosing problems.

==Times==
* This data originates from different studies performed under different OS versions and use cases.
* Please add the source and a short note about the conditions you used, and if necessary more detailed ones to the Talk page.
{| class="wikitable"
!Mode
!Time
!Details, Source
|-
! Active PND applications
| 10-20 hours
| OS SuperZaxxon, Beta 2, Kernel 3.2.1
|-
! MP3 play, screen off
| 43 hours
| MP3 playback in [http://repo.openpandora.org/?page=detail&app=audacious Audacious] in [http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 OS SuperZaxxon, Beta 2, Kernel 3.2.1]
|
|-
! Lid Closed
|16-23 hours
| estimate, depends on WiFi, OS Zaxxon, Hotfix 3
|-
! Low Power Mode
|30-75 hours
| [http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 OS SuperZaxxon, Beta 2, Kernel 3.2.1]
|-
! Power off
|5% charge loss per week
| although there are reports of much faster drain?[http://boards.openpandora.org/index.php?/topic/24-battery-drain/]
|-
! Mains charge, operating
| 20 hours
| estimate, OS Zaxxon, Hotfix 3
|-
! Mains charge (low power)
|8 hours
| estimate, OS Zaxxon, Hotfix 3
|-
! USB Charge, operating
| 20 hours
| inactive, screen+wifi on, may charge or discharge depending on load
|-
! USB Charge, low power
|20 hours
|estimate
|}

==Battery Care==
* You can charge your [[battery]] to full charge, the charging circuits will then reduce the current to avoid overheating
* If you won't use the [[battery]] for more than a week, it is best to leave it at about 40% charged (as opposed to full)
* Don't worry about running it down too low, there are protection circuits to avoid a '''damagingly low discharge'''.
**Avoid leaving the battery completely discharged though. When the power runs out, the system will be unable to shutdown cleanly, and might corrupt your files or the system.
* No harm will come if you only partially recharge it. If you've only got 10 free minutes to charge before leaving, go ahead. You'll put an hour of usage back into the battery, and you can always charge it more later.
* For best accuracy, the battery meter relies on watching the battery discharge over most of it's range (down to say 10%).
**This will only affect the 'time to run' indication
* If you're not going to be using your battery for a very long time, the extremely best thing you can do for it is to discharge to 40%, seal it in an airtight bag, and put it in the fridge. Even years later, you pull it out, and it will be almost as good as when you put it in.

[[Category:Power supply]]

Talk:Power modes

2012-04-08T21:14:01Z

Porg: /* Release SuperZaxxon, Beta 2, Kernel 3.2.1 */ new section

"10-20% per day charge loss (est)" - mine does not discharge nearly this much on it's own while powered off for a day. --[[User:Cheese|Cheese]] 07:13, 26 June 2010 (MEST)

That was borrowed from some forum chat, it would be good to collect some numbers (see table below), both for going through a power cycle (chews battery on my phone) and powering up after 12/24/48 hours off. I also wonder if some batteries are more leaky than others. 50% loss over a weekend was (i think) quoted.--[[User:Tsh|Tsh]] 19:43, 26 June 2010 (MEST)

==Self-discharge==
Off 13 hours = 100% -> 99%. (tsh) 
Off 18 hours = 97% -> 97% (cheese) 
Off 13 hours = 39% -> 44% (Ivanovic, FS#136)

Based on this, maybe taking a reading immediately after power on is not reliable, so I now suggest taking 2 readings, one immediately after power on, one 15 min later (after sitting idle) --[[User:Tsh|Tsh]] 12:48, 5 July 2010 (MEST)

The total battery drain over the course of one week and one day, with a few minutes of usage on two occasions, was 6%. [http://boards.openpandora.org/index.php?/topic/24-battery-drain/page__view__findpost__p__6088]

==Charge times==
Low power 1:36 17%->51% (->63% after 3 min not charging)(tsh)

==Low power==
"the CPU max speed is set to 14 MHz"

Is it still true ?--[[User:Linux-SWAT|Linux-SWAT]] 00:37, 27 May 2011 (MEST)

== All off (as low power state) ==

With WiFi off, screen off (Hotfix 3)

500 MHz 4h10m 81%->63% (~23 hours battery life) 
50 MHz 4 hours, 62% -> 45% (same as above)

Hotfix 4
250 MHz, opp1 2:55, 10% (30 hours)

== MP3 only ==

500 MHz 63 min, 6% (17.5 hours)-exaile 
500 MHz 2:54, 16% (18 hours) - ommpc 
500 MHz opp5 1:15, 7% (18 hours) - deadbeef 
900 MHz opp5 2:30, 15% (18 hours) - deadbeef 
250 MHz oop1 2:30, 15% (18 hours) - deadbeef 

== Release SuperZaxxon, Beta 2, Kernel 3.2.1 ==

[http://boards.openpandora.org/index.php?/topic/7196-32-kernel-issue-tracking-thread/page__st__200#entry138048 Study by porg] -- [[User:Porg|Porg]] 23:14, 8 April 2012 (CEST)

User:Porg

2012-04-08T20:43:29Z

Porg: Created page with "[http://boards.openpandora.org/index.php?/user/1441-porg/ My Pandora Profile]"

[http://boards.openpandora.org/index.php?/user/1441-porg/ My Pandora Profile]

Talk:Pandora FAQ

2012-04-08T20:18:45Z

Porg: /* Battery Inaccurate */

== Battery Inaccurate ==

They're going with a 10-100hr battery instead, custom-made, last we heard. The Wiki needs to be updated. I'll do it later today, but in case anyone else wants to do it... :)
: Done.[[User:Chip|Chip]] 21:55, 27 April 2008 (CEST)
:: Battery runtime has improved a lot with SuperZaxxon, using Kernel 3.2.1. Updating section accordingly. -- [[User:Porg|Porg]] 22:18, 8 April 2012 (CEST)

== font ==

The Pandora font seems to be really close to WerkHaus Medium according to What The Font: http://spatula-city.org/~im14u2c/images/pandora_werkhaus_medium.gif If you replace the 'a' with a 'd' whose stem has been chopped and round all the sharp corners slightly, you arrive at the final result, I think. --[[User:Intvnut|Intvnut]] 07:29, 13 May 2009 (CEST)

== A2DP Encoding ==

Does this hardware do A2DP encoding? One big problem I had with the Openmoko Freerunner is that it would support A2DP headphones through bluetooth, but only if you did it in software through ALSA or gstreamer via the bluez stack, which would chew up a bunch of CPU and the audio would skip if ever the system needed the CPU time for something else.

I got a Nokia N900 instead and it seems to do its A2DP encoding in hardware so I was able to find a good open source solution for listening to my podcasts, but I'm also interested in this device.

[[User:Daniel.benoy|Daniel.benoy]] 17:56, 25 May 2010 (MEST)

== QEMU and some ARM hacks for emu choices (limited) ==

First, there are no good solution here, just some info.
[http://www.gp32x.com/board/index.php?/topic/48726-qemuonarm/| QEMU runs operating systems at 140mhz] on GP32X. So the Pandora could do it somewhere between 280mhz to 400mhz? Also, I use QEMU on my Android (ARM) for various things (but not games). Anyway, QEMU should provide a way to run _older_ (Pentium era) PowerPC and x86 stuff also right?
Reportedly, Windows is problematic when virtemu-lated on ARM but [http://www.reactos.org/wiki/ARM_Port| ReactOS on ARM] is a lot friendlier to the architecture (as it can actually be compiled for ARM). ReactOS being a the result of clean-room reverse engineering of Windows for the purpose of a total copyleft replacement of the beast. But likewise, ReactOS is not that practical in its purpose yet.
There are also PowerPC versions of windows NT 3.1 to 3.51 (the platform must be fully PReP compliant, Macs cant do it) (Also Alpha and MIPS, btw).
Microsoft has announced [http://www.winrumors.com/microsoft-demonstrates-early-build-of-windows-8/| ARM compatibility for Windows 8]. However, I wouldn't count them following through anytime soon (_maybe_ Windows 10 will deliver). If they follow their usual pattern, this announcement is simply to hold off customers from buying competing software until Microsoft can jury-rig a suitable snake-oil solution to convince customers they really never needed the competitor's software or Windows on ARM to begin with.

Libpnd hub

2012-01-18T01:01:52Z

Porg: /* Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file */ Update: Changing HOME variable to PND dir was only necessary before Pandora OS 1.6

:''Basic users will be more interested in the page [[Introduction to PNDs]]''

{{TOC limit|limit=3}}

{{split section|To much text, a lot of things could be outsourced to dedicated shorter articles}}

=Overview=

[[libpnd]] is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)

[[libpnd]] thus is a collection of:

* handy system code that hopefully is reusable - IO functions, CPU clock setting, etc.
* applications for supporting the Pandora's unique features, such as ''pndnotifyd'' for auto-discovery of PXML and .pnd applicatons
* libraries for support of the .pnd and PXML systems; i.e.: for locating, executable, mounting and unmounting PXML-directory and .pnd applications, loading PXML and handling overrides
* hopefully reusable code for support of these things; i.e.: a rudimentary but useful config-file parser, rudimentary singly-linked-list container, etc.

It will also include utility functions for setting the CPU clock, reading GPIO inputs without depending on SDL, and other handy bits.

'''You can, nay, are required to - contribute to libpnd!'''

==Design considerations and philosophy==

While much of [[libpnd]] is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..

* simplicity - just work right, configuration not generally needed
* obviousness - work as one would expect for this sort of device; i.e.: the user assumes something will work a certain way, and it does
* like other guys - as an extension of the prior point, we have tried to follow UNIX spirit and provide reusable small tools to do the work those bits can be leveraged, but further tried to follow the spirit of other consoles. So while the device is a powerful little computer, it is probably going to be used by gaming and retro enthusiasts and so we color some of our decisions that way. (i.e.: consider that a PS2/xbox/PSP/etc will have save-game or data management as a separate application, for instance. If thats the best multi-million dollar companies can come up with over decades, well, its not so bad for us to fall back on!)
* not over-defined; libpnd and PXML try to define a bunch of things, but we also do not _over define_; we try to lead by providing examples and styles, and while we have designed ahead for many things, we have also not nailed a lot of that down too early. It is better to be simple and shipped, then complex and a mess.. adaptable rather than scary.

The library is of course broken into parts:
{|class="wikitable"
!Part!!Comment
|-
|include||include these files to make use of the lib
|-
|lib||the code that produces the lib
|-
|test||mini tools to test various pieces of the lib in isolation
|-
|bin||test tools - tools for testing the lib as it is developed, not anticipated to be used by many
|-
|testdata/||for testing /etc/pandora; will contain 'conf' dir, for example
|-
|apps/||actual applications people may use, such as [[pndnotifyd]]
|-
|}

For now though, here are a couple notes about the design.
* it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it). I have gone out of my way to limit external references so that bindings are easier to make.
* contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.
* I have tried to keep the API relatively simple and am faking some OO like data hiding to try to keep dev noses out of structures that are subject to change. i.e.: functions for list management and node access are provided, don't dig into the void* cast structs, or you could get burnt.
* the API should be pretty stable; so far very few user-code changes have ever been needed.. lib internal changes should be binary compatible.
* As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself
* As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)
* The lib works pretty well, but there is room for improvement internally; it won't hurt my feelings for you to suggest improvements, and I'm sure we would all be grateful for any patches you provide. We've _started_ this library, but by no means wish to carry it alone!

==Opportunities for improvement==

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

* Better ISO lang handling ... due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)
* Validation of files when they're loaded
* An actual parser of PXML metadata

[[New PND format | This page describes a proposed new PND format.]]

==License==

libpnd (including all the apps etc) are released under the LGPL (ie: so there should be no encumbrances that prevent linking to commercial applications.):

GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999

==Obtaining the library==

libpnd is in the Official Pandora GIT repo: [http://git.openpandora.org/cgi-bin/gitweb.cgi]
To obtain yourself a copy, use something like:
<pre>
git clone git://git.openpandora.org/pandora-libraries.git
</pre>
Thats all you normally need. For copy-paste from the private Wiki sake, heres what I had before:
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:

<source lang="bash">
mkdir libpnd
cd libpnd
git init
git remote add libpnd ssh://foo@git.openpandora.org/srv/git/pandora-libraries.git
git push libpnd master
</source>

==Building the library==

Standard 'make' should be sufficient here; pull down the directory from the GIT, cd into it, and run make. Thats it.

Note that the make default target is 'everything', which will emit:
<source lang="bash">
libpnd.a - the static linked version of the lib
libpnd.so.1.0.1 - the dynlinked version
libpnd.so.1 - the stub for the shared lib; i.e.: apps should link against libpnd.so.1 and not the 1.0.1 over-specific version
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin
</source>

There are a few additional make targets, however.

{|class="wikitable"
!Target!!Description
|-
|make clean||wipes out the object files, the bin files, and *~* (emacs backup files), empties some of the deploy stuff, etc. Do this before committing to GIT or we will beat you with sticks.
|-
|make deploy||populates the deploy/ directory, which is what is used inthe shipping images; i.e.: testdata/conf includes test configs, while deploy/etc/pandora/conf includes the configs we ship with. This
|-
|make||will copy over some of the libs and binaries and such.
|-
|make pnd||create a few sample pnd files for testing the lib on an x86 machine
|}

==Included Applications==

===pndnotifyd===

Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need [[pndnotifyd]], though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)

===pndvalidator===

Is mostly a skeleton right now; in the future, it is hoped it will inspect a PXML.xml and then check to ensure the referenced assets are present; the goal to validate the PXML.xml is spec compliant, and the resulting application would be useful.

===discotest===

One of the test tools; it essentially runs an auto-discovery to list off the found apps (be they PXML.xml dir apps or .pnd files), and can dump various data or invoke one or other little tasks; used to test lots of
bits of [[libpnd]] as it was developed.

===rawpxmltest===

Reads a given PXML.xml and spits out some of the fields found within.

===Test tools===

See the test/ dir in the libpnd source for assorted goofy little test apps used for testing bits of libpnd over time. They also may serve as source examples for using some of the APIs. They're old and shoddy probably too.

==How does it work?==

This is just a quick summary to save you guessing by reading [[PXML_specification|this whole document]].

In essence, libpnd includes lots of real code, but in many places it passes heavy lifting off to shellscripts. This is both handy because the scripts are easily modified without recompilation, and further extends our design goals of making the library bindable to any other language.

Remember, PXML.xml directories are just as executable/mountable as .pnd apps.

So while libpnd is mostly straight-C and so easily bound to python or perl or whatever, libpnd itself invokes many scripts. Those scripts can be directly used by other applications, including other shellscripts.. so libnd functionality can even have bindings in other scripts. This is very flexible and powerful, and handy during debugging or SSHing into the Pandora, etc.

The application lifecycle goes like this:

* device is turned on
* during init, pndnotifyd is brought up and inhales the config giles
* pndnotidyd will attempt to auto-discover what PXML.xml directory apps and .pnd-file apps are in the configured searchpaths
* pndnotifyd will set up filesystem watches on the directories in the notify searchpath; if any of those directories are touched, pndnotifyd will wake up and re-auto-discover .. possibly removing .desktop entries or creating new ones. (i.e.: you drop a new app into the app searchpath, or remove one, or mount an SD card, etc. This is how appications immediately show up or vanish from the window manager desktops.)
* a libpnd aware launcher can execute applications direct (using libpnd)
* a libpnd unaware launcher can execute applications via the .desktop standard system; pndnotidyd will emit .desktop files as needed.
* when libpnd or a .desktop file need to execute an application, they do it via pnd_run.sh (which may be leveraged by other applications, but they hould use libpnd if they can instead, for utmost compatiblity down the road.) pnd_run.sh does the mount of the ISO, runs the actual execable and so on, as directed by libpnd or the command-line args from the .desktop. pnd_run.sh will clean up after everything as well.

So it all works like magic, but it is not that complex a system once you've got the hang of what all is going on.

application → libpnd → shellscripts → system

==FAQ: IF you want to make files visible to the apps, do you have to modify the pnd?==

No. When apps write back to themselves, the writes go to their /pandora/appdata on the SD that houses them. The next time the app reads a file in its directory, the OS will ensure they get the newer file, which is the one in the appdata.

Likewise, you can just drop a file into the appdata and the app will see it.

The app doesn't know about appdata and its pnd file.. the OS and libpnd take care of all the magic.. the app sees one directory, but the reality is there is magic merging going on behind the scenes.

==Assumptions about the filesystem and Configuration==

Note that for libpnd to work, it makes certain assumptions about the filesystem and config files. Since libpnd was developed with the images it should work for the Pandora .. but just dropping libpnd onto another Linux distribution and it won't likely 'work out of the box'. Certain config files will need to be set, and certain conventions followed.

===Searchpaths===

libpnd was designed so that most everything is configured in files, and that these files should be easily hackable and easily overriden, without compromising the machine. It should be feasible to add a config file to an SD card, have it take over if available when required, and then 'undo' those configs simply by removal of the SD card and rebooting.

To facilitate this design goal, all config files are 'sought' using a search-path system.

Developers should be mindful of using the libpnd APIs so this behaviour is inherited to interested applications; developers could also reuse the logic for searching for files, if they find it useful.

Searchpaths are colon-delimited list of paths, searched left to right.

ex: foo:bar:/my/baz means to look for a given file in 'foo', then in 'bar', then in '/my/baz'.

The standard config files have a default searchpath, and those config files will define further searchpaths for scripts and such the system uses. This makes the system highly flexible -- default scripts are included, but can be overridden by dropping the right named script on an SD card, or by altering a config file.

See the example config files below for example searchpaths -- i.e.: how pndnotifyd searches for pnd_run, etc.

===Notification paths===

The 'apps' config includes a searchpath that specifies the sub-paths to be 'watched'. Various watch mechanisms exist for various filesystem types, but over the course of Pandora development (various kernels, various k-modules, various DM and WM's, I found the included system most stable, though not most current. After a final device image is settled on, it might be time to alter the notification system, but it should not impact the libpnd API.)

Anyway, watches are placed upon the paths defined, and if anything in those paths changes, the auto-discovery code is kicked off to seek our PXML.xml and .pnd type applications in the search paths.

Note that searchpath and notifypaths are different (and usually very similar, but have the option to be very different.)

===Config files===

libpnd includes a generic simple config file parser and assumes the presence of a few config files. It also includes defaults
so if a config is missing or broken things should work.

In general, Pandora specific config files should be located in:
<pre>
/etc/pandora/conf
</pre>

The config files are:
{|class="wikitable"
!!File!!Description
|-
|conf||this file is generally _not_ included with the Pandora and left to default; its job is to define the basic default searchpath for config files, so should you wish to override things entirely, you may need to alter this file. i.e.: If you wish to switch to test config files on SD or in /tmp, instead of using any other conf files .. you can create this guy. This provides a mechanism to short circuit the entire conf system.
|-
|apps||this config file defines auto-discovery and other application bundle parameters
|-
|desktop||this config defines "dotdesktop" .desktop and FreeDesktop integration paramters -- example is where to spit out icons or .desktop files from discovered PXML.xml or pnd applications
|-
|categories||this config maps PXML.xml spec based categories to FreeDesktop standard categories; in this way a PXML based applicatoin can show up in the appropriate categories of a WM that does not use libpnd
|}

====conf File====

No default is included with the distribution.

The default search path is reasonable and assumes we want the official /etc/pandora/conf near the end, with checks to the SD cards for overrides first. (Likely most people will not override, so the canonical location will be used 99.9% of the time.)

<pre>
#define PND_CONF_SEARCHPATH "/media/mmcblk0p1/pandora/conf:/media/mmcblk1p1/pandora/conf:/etc/pandora/conf:./testdata/conf"
</pre>

The key for override is:

<pre>
#define PND_CONF_KEY "conf.searchpath" /* if not found, use PND_CONF_SEARCHPATH */
</pre>

Which suggests using something like this.

<pre>
[conf]
searchpath /foo/bar:/baz/bing
</pre>

====desktop File====

<pre>
# Open Pandora
# Desktop configuration

[dotfiles]
#(~/Desktop for xfce, /usr/share/applications for WMs that actually follow spec)
dotdesktoppath ~/Desktop/ # path for pndnotifyd to spit .desktop files into (run as root)
iconpath /tmp # path for pndnotifyd to drop icons into (can be same as .desktop if WM permits)

[launcher]
# if hupscript is commented out entirely, pndnotifyd will not try to find/run the hup
# if it is uncommented, pndnotifyd will attempt to invoke the hupscript after emitting .desktop files
# (the hupscript exists to hup the WMs to redisplay .desktop apps)
#hupscript pnd_hup.sh
</pre>

====apps File====

<pre>
# Open Pandora
# Application configuration

[autodiscovery]
# searchpath is a list of paths (colon separated) in which to look for PXML.xml or .pnd-file applications
searchpath /media/*/pandora/apps:/usr/pandora/apps
# notifypath is a list of paths to monitor; if anything in those paths changes, the searchpath is rescanned
# note that for each path chunk, all current subdirs of that path are also watched)
notifypath /media:/media/*/pandora/apps:/usr/pandora/apps:./testdata/app?

# PXMLs may be overridden .. i.e.: overrides are a subset of PXML, where the values are copied over the full PXML
[overrides]
# searchpath to look for PXML overrides (which are named by the unique-id)
searchpath ~/pxml-overrides

# [pnd] defines where to locate the pnd support scripts, so the user may override pnd_run.sh without clobbering built in
[pnd]
searchpath /media/*/pandora/scripts:/usr/pandora/scripts
runscript pnd_run.sh
</pre>

====categories File====

<pre>
# Open Pandora
# dotdesktop configuration

# this config file maps 'PXML' categories to free-desktop standard categories
# i.e.: category 'Foo' could map to more standard 'Utility', thus making .desktop file
# emitting a more useful thing

# the standard listing of categories is:
# http://standards.freedesktop.org/menu-spec/latest/apa.html

# note that 'map' section in the config is _required_ for a match to be found; this
# is done to separate categories from (future) top-level directives

default Application;Utility;Network;

[map]
Development Development
Education Education
Games Game
Graphics Graphics
Internet Network
Multimedia AudioVideo
Office Office
Settings Settings
System System
Utilities Utility
</pre>

===SD card layout===

libpnd concerns itself with things in the 'pandora' root folder on SD. We agonized over this decision, but settled on this to avoid cases where someone with a 16GB SDHC card puts 50-million files with ".pnd" on them, and expects reasonable performance. Instead, applications for instance would have to be in:

<pre>
/pandora/menu -> apps that will go to /usr/share/applications and should show up in xfce menu by category
/pandora/desktop -> apps that will go to ~/Desktop and show up on user desktop as icons
</pre>

The following location is used by pmenu (and may get deprecated, but I've not discussed it with cpasjuste yet.)

<pre>
/pandora/apps
</pre>

i.e.: the searchpath for autodiscovery includes /media/*/pandora/apps (and desktop and menu now)

Also in the /pandora/ folder is a magic 'appdata' folder:

<pre>
/pandora/appdata
</pre>

When a .pndfile or PXML.xml dir get mounted, any writes back to the mounted area are put into appdata, with a subdir by the unique-id. i.e.: With the hypothetical MAME.pnd, it might update its config files after a user changes something, or create new files, or store hiscores or whatever. If it doesn't write them to [[NAND]], and doesn't want ot write them to /mame/some/dir, but instead record it to itself for whatever reason, it would go to /pandora/appdata/MAMEs-ID/ instead. The pnd or PXML.xml app area is never modified during a run, only the appdata. (But when an application reads its own path, it will pick up the appdata version of the file instead of the actual file. Then magic of union-type filesystems!)

Example:

If Myapp with unique-id foo.123 is mounted, then any write-backs are directed to..

/pandora/appdata/foo.123/

On the SD that hosts the application.

===NAND layout===

In addition to seeking applications in [[SD cards]], /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.

It might be a cool addition to put a user homedir into the searchpath as well, so [[NAND]] but user-homedir (for on-device browser downloads, say.)

==Command line tools and testing==

A number of scripts and tools are included or built with libpnd, to facilitate testing of the lib as its being developed and to assist in making .pnd files and PXML.xml files.

==PXML.xml and .pnd files==

On most platforms, applications are distributed as an executable and optional datafiles and likely an installer. The installers job is to integrate the application into the filesystem, as the transport mechanism itself is not executable and is considered temporary. In Windows an application might be installed into Program Files, while in Unix an application might be dropped into /usr/local/bin .. data files in various other places.

For the Pandora platform we wanted a very easy to use workflow -- download and run -- and also have a very different operating environment. With multiple SD cards available for expansion (and that space being highly desirable due to a smaller internal store) it is desirable to install applications to SD, and yet SD cards are by definition something users will wish to carry multiple of. With two slots, it could be quite a chore to install an application to SD1, its data to SD2, and then say have only one of them plugged in at a time, or switch which slot they're in, or any number of scenarios. i.e.: Installing onto a medium which may be present or not at any time is very different to how most operating systems work. So we made something new and awesome.

The PXML.xml and .pnd-file approach we came up with attempts to address these issues.

The goals:
* for the user, an application can be a single file download
* furthermore, there is no installation whatsoever, beyond dropping that single file into the right place on the SD card
* using the application should be easy -- stick in the SD card, and tap/launch on the icon.
* for uninstallation, delete the single file. Thats it, no fuss.
* for the developer, creating that single file should be easy to do
* for the system, performance should be high

Remember, an application can be a .pnd 'bundle' (single file containing all the sub-files), or a PXML.xml 'dir application' (an unpacked .pnd esentially.) '''BOTH PXML.xml-dirs and .pnd's ARE EXECUTABLE.'''

pndnotifyd will auto-discover PXML.xml in a directory and consider that an application, emitting a .desktop file, just as well as a .pnd file. i.e.: This can be hand for development or users. Remember that a mounted PXML.xml dir still redirect write-backs to the /pandora/appdata directory, just like a full .pnd application. They are treated the same!

===What are PXML.xml and .pnd files?===

PXML.xml is a file describing an application
A directory containing a PXML.xml _is executable_
A .pnd file is the packaged up version of the directory that is executable.
i.e.: a PXML.xml in a directory is just as executable as a .pnd representation of that directory.

Example:

<pre>
mkdir OutcaST
cp outcast.bin OutcaST/
cp PXML.xml OutcaST/
# at this point, the OutcaST directory is now discoverable and executable
</pre>

pnd_make.sh -this -that OutcaST outcast.pnd
# at this point, outcast.pnd is executable (as is the OutcaST directory), so upload outcast.pnd to the Open Handhelds Archive and let people enjoy!

===A note on including shared libs===
A philsophy for packaging that I am advocating is to 'just make applications work' -- avoid dependancy trees.

Some guidelines:

1) you can depend on shared libs included with the firmware to always be there

2 you should include any shared libs you need for your app, that are not in the firmware (yes, this increases app size a little bit, and potentially makes for duplication among apps that use the same shared libs)

3) if a shared lib becomes desirable in the firmware, it can be added there as a firmware patch easily (this has the advantage of gradulaly updating the entire user based, and apps easily saying 'we depend in firmware version X', rather than making for pnd-dependnacies and the equivilent of 'dll hell'

4) You'll have to be careful in linking your application to ensure that the shared libs you are including in the pnd/PXML-dir are to be locatable by your binaries. ie: stick them in a 'lib/' dir in your bundle, and stamp your binary with a library-path './dir/' so they can be found, say. More later.

===Future idea: pnd's for containing system-wide shared libs===

This is something we've bounced around for quite awhile, but not committed to. As it keeps coming up I thought I'd put some notes here in public.

It is possibly desirable to make a special searchpath that is discovered during machine boot, and any pnd's found there are automatically mounted (and left mounted) into a special path (say /usr/local/pandora/lib or somesuch.) This way, collections of handy utilities or shared libraries could be distributed as a pnd, and become available in consistent locations. If 10 applications need a shared lib, and don't want to duplciate it in each of their pnd files, this could be an approach.

I tend to think it is best avoided, however, since it complicates the user experience -- we end up with pnd depandancies, and apps nolonger about to 'just work', and apps that did work and 'suddenly break' when other files are altered. The philosphy we're going for with pnd files is 'drag and drop' -- user downloads a pnd file, and it works.. a self contained application, nice and easy. We start complicating the dependancies, and it turns into 'dll hell' as seen on other platforms.

That said, it is _not_ difficult to add into the existing system and design; we've been mulling it over, but it is best avoided for now. rather than complicate the system up front, let us try to get a functional and as lightweight-as-possible system on the uptake, gather some usage data points and then worry about upgrades :)

===File format - PXML.xml / PXML Specification===
See the [[PXML_specification|PXML specification]]

Alternatively the spec is included in the docs/ directory of the libpnd distribution, though the wiki version linked above should be considered cannon.

A note on history; the PXML spec was originally created by EvilDragon, and went through a number of revisions as suggestions came in; as these things are wont to do, the target was ever moving and the scope and meaning of PXML changed so at some point a more strategic approach was needed. dflemstr took it upon himself to help recode some of the parse and re-evaluate many of the PXML decisions and hence was born the PXML-version-2 spec.

===File format - .pnd files===
The pnd file format is pretty straight forward, though most will interact with it through the included (or community supplied) tools.

Basically its just an ISO file (or other filesystem type) with a PXML.xml and an optional PNG icon appended. (example: cat appfolder.iso app.pxml icon.png > app.pnd) For ease of discussion, I refer to ISO but in fact you coudl be using squashfs or other types.

The ISO filesystem portion of the file can include anything the developer wishes, as long as it includes a PXML.xml in its root file and an executable somewhere in there. It can also include images, audio files, data files of any kind. It can be small or large.

Yes, the PXML.xml is included in the ISO portion (in the root directory), and also appended to the end of the .pnd file (for _convenience_ .. it is very easy and fast to locate in this position; we can backseek into the ISO to find the PXML, but if its a 500MB ISO it could take awhile. Hence, we append it and can find it in one seek.)

'''NOTE: The naming of the PXML.xml file is important! The name is case sensitive and must be "PXML.xml", nothing else!'''

This simple format makes it possible to easily create .pnd files with the default utility's of most operating systems. Further, it is a fairly fail-safe system -- the PXML is appended, but is also included within the ISO image part of the file so if the appended-PXML is ever lost (unpack and repack poorly, say) the system will still work (the PXML inside the ISO can be found easily, even without mounting the ISO _as_ an ISO, since it is a plaintext uncompressed image format.)

Manually creating a .pnd (or even a PXML) is a pain so there will be a few helper scripts or maybe even a gui app out when we launch.

Included with libpnd are some scripts to create PXML and pndfiles, though it is expected people will create handier utilities. See the tool section of this wiki for some details.

Question from the gp32x forum regarding confusion of PXML location -- remember that in general most developers will keep a directory that represents the .pnd or PXML-dir application. Their makefile/build-process will drop the executable(s) into that directory, which inludes a PXML.xml description of the application, and possibly an icon (and whatever all else they wish.) To build the .pnd file, a script (say) is used which compresses all this into the pnd format (including appending the PXML.) So yes, the PXML is in two places in the .pnd file and one place in the source directory. You'll get used to it ;)

Rationale --

Several iterations of pnd files have been considered, from zipfiles to cramfs to other formats, to putting in a key/value set of information tags in the file, to table-of-contents indexes, to any number of options to help performance, and so on. In the end we went for a good overall and simple solution and dropped getting fancy -- PXML.xml can be extended to define the type of the file if it cannot be magic'd, so we could using other filesystem types in the future (and this is why people should use libpnd rather than rolling their own solution.) For now however, pnd files are ISO files with the PXML.xml appended and an optional icon. This keeps the PXML and icon easy to locate, and yet a easy file format.

====Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file====

These are guidelines to make pnd-files 'well behaved', and to help move towards a consistent pnd structure.

* Always include your icon png-file and PXML.xml file in the _Root_ of the pnd-file; this is for reasons that folks may well unpack the pnd-file, and then repack it; in doing so, if the icon and PXML.xml (normally appended to the .iso to become a .pnd) will be lost, unless the user or tool is being careful. Thus, it is wise to include them within the .iso, to make things so the iso is the entire pnd application, in unpacked form.

* Use a 'reasonably unique' unique-id of course (to identify your application.) This is used for many internal uses, so uniqueness is pretty wise.

* Use an 'application relevant' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.

* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code ... just have your 'runscript' do something like 'export HOME=$(pwd)' and you're good to go! '''Note: At the latest as of Pandora OS release Zaxxon with Hotfix 6, changing the HOME variable to point to the PND working directory is not necessary anymore as the OS takes care of changing the HOME variable of a PND session's variable environment. (Info from Skeezix)'''

* Try using rudimentary [http://en.wikipedia.org/wiki/Zenity Zenity] scripts to pop up imporant pre-run information to the user via the GUI, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line Zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened

* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.

* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)

* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.

* For data that is not kept in your appdata directory, try to keep it local to the current SD _or_ better still, search both SD. ie: libpnd uses a basic but really handy system for iterating across a list of directories (including glob type expansion); so you can tell it something like /media/*/foo:/tmp and it'll check every mounted device (including both SD slots) in the 'foo' directory, as well as /tmp; you can have it call your code as it looks through, or you can ask libpnd to find a file for you and report where it was found, across all your searchpaths; you don't have to use libpnd's code to do it, you coudl write oyur own (using libpnd as an example if you need the help), as its pretty easy to build (20 lines of code maybe?) Anyway, the trick is to be multi-SD aware, and bonus marks for handling if theres a USB mounted drive etc as well. (Example; I coded minimenu so that when it caches out a preview picture, it checks for free space first, and tries first on the same SD that the pnd is mounting from, and then across a searchpath of alternate locations to cache to; this way the user can customize the caching, and it can be on various devices.)

====What filesystem types can be contained within a pnd-file?====

The pnd container can really contain a large variety of filesystem types; day-zero we're aiming for ISO since it is simple, easy build across every major OS, and fast to use. But it is not the only supported filesystem type, and more should be added all the time. (Possibly '-auto' can be added to pnd-run and it'll "just work" for dozens of types!)

A compressed filesystem type has always been desirable for file sizing reasons, though it potentially impacts performance (depending on the application operation really.)

Supported types (not an exhaustive list!):

* ISO
* squashfs

===Creating pnd files===

The [[PND quickstart]] page contains this information.

===PXML overrides===

There are a couple of ways to effect an override of the PXML, without modifying a pnd-file.

===="In-path" override files: .ovr====

The library automatically imports a limited number of overrides from a conf file that can be located in the same location as its matching .pnd file is.

For instance, if /pandora/desktop/awesomegame.pnd exists, then libpnd will automatically also search for /pandora/desktop/awesomegame.ovr

Some menu systems will also be smart enough to watch for an icon override -- /pandora/desktop/awesomegame.png -- and if present, to use it; 'minimenu' (mmenu) is aware of that, as is pndnotifyd daemon when emitting .desktop files. Likely pmenu will also be updated. In effect, the user can override the icon, category and other attributes of the pnd, without needing special tools or to alter the system.

An .ovr file must be named identically to the pnd-file, excepting the 3 character file extension.

NOTE: Given that a pnd may emit multiple applications from its PXML.xml, the ovr will have to be aware of this so it can override the correct application(s) within the pnd. Some menus and information tools will display the application list with 'subapp number' to assist identification. minimenu shows the subapp number in the detail panel, for example. In the case where a pnd-file has only one contained application, that is subapp-number zero. For any additional subapplications, increment by one .. but it can be tricky to know which app is which subapp number. (A careful eye will notice the .desktop filename includes the subapp-number after the pound sign .. foo#3.desktop is subapp_number 3.)

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 note text line 1
</source>

====PXML override file -- currently unsupported====

PXML.xml files can have any number of their elements over-ridden by user preferences.

The design goal here was to make it so user-preferences could alter the impact of the PXML.xml in any way, but without requiring the actual PXML.xml in the .pnd (and within the ISO therein) to be altered (could be a 500MB ISO after all!), and further, for these changes to persist. Consider than an SD card could be removed and inserted into the other slot, or the app could be removed entirely and come back another day, or other scenarios.

As such, the PXML-overrides are kept in NAND in the user homedirectory (See the config files to find out where.)

libpnd includes functions to pull in PXML, and also functions to then look for and merge in overrides. It is not always done since you may wish to inspect the PXML or the overrides, so the developers job is to do as they see fit -- pull the XML, and likely also pull in the overrides.

At this time I'm not sure if people will ever use overrides, but the system has been built in should it be needed.

===Included shellscripts to generate files and other sundry duties===

====genpxml====

This tool can spit out a basic but correct PXML.xml, faking up a halfway-useful unique-id in the process. It might be handy in saving you writing up a PXML.xml from scratch.

====pnd_hup.sh====

pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out whom to HUP.

====pnd_make.sh====

This is one of the great ones :)

Given a directory with a PXML.xml (see genpxml above) and an executable and any other goo you want in there, this script will spit out a .pnd file you can execute or distribute as an application.

====pnd_run.sh====

This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it dorectly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.

==Auto-discovery of applications==

TBD.

==Integration with FreeDesktop .desktop systems==

===dotdesktop (.desktop) files===

===Icons===

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.

==APIs==

Feel free to just go read the .h files; I have tried to comment liberally :)

===Setting and Getting the CPU clock speed===

===Device paramaters - brightness, etc===

===PND files, exec and mount===

===Application discovery===

===Config file parsing===

===Boxing, the singly-linked list container===

===Directory watching===

===Logging api===

[[Category:Development]]
[[Category:PND]]

PND nub modes

2012-01-16T18:36:53Z

Porg: Added new method. Restructured whole article.

{{IntroNote | This page is a work in progress, the instructions in here may or may not work for you. They were copied from several forum posts (see inline references). For an introduction to PNDs, see [[PND quickstart]]. }}

If you want a different nub behavior for certain PND applications, you can achieve this by using one of the presented methods here.

== Rationale ==

Why would you want to do this? Simple; at least one person has reported that, when playing a natively-ported FPS (like Duke Nukem or Quake, but not GoldenEye) on the Pandora, using the right nub as the mouse has proven to be more comfortable and less awkward. But switching nub modes manually is annoying; so let's have Linux do it for you!

== Presented methods ONLY apply per PND, do not affect general behavior ==

The methods below are crash save, as the nub behavior is changed by the process pnd_run.sh, which runs before AND after a PND is running. Thus even in the event that your PND application crashes, your nub configuration WILL be the same as before you started the PND with the custom nub behavior. (Source: [http://boards.openpandora.org/index.php?/topic/2860-tutorial-how-to-have-your-nubs-change-modes-upon-launching-of-a-pnd/page__view__findpost__p__118299 sebt3 forum post])

== Method: Switch left/right nub unix devices ==

Hint from: [http://boards.openpandora.org/index.php?/topic/2860-tutorial-how-to-have-your-nubs-change-modes-upon-launching-of-a-pnd/page__view__findpost__p__49157 Blue Protoman]

=== Step 1 ===
You must download sebt3's new [[pnd_run.sh]] installer and run it. Get it [http://sebt3.openpandora.org/pnd/pnd_run_installer.pnd here]. 
'''Note: This step is no longer required as of Hotfix 6 Alpha 1.'''

=== Step 2 ===
Open a text editor and copy/paste this:

<source lang="bash">cat /proc/pandora/nub0/mode > /tmp/nub0mode_before
cat /proc/pandora/nub1/mode > /tmp/nub1mode_before

echo "mbuttons" > /proc/pandora/nub0/mode
echo "mouse" > /proc/pandora/nub1/mode</source>

This will back up your current nub modes, then switch them; the left will act as the mouse buttons, the right will act as the mouse. If you'd like, you can substitute "scroll" or "absolute" (joystick) in, depending on how you like your nubs. But you must save this as '''PND_pre_script.sh'''. Save it wherever you'd like, you will be moving it elsewhere later.

=== Step 3 ===
Copy/paste this into the editor again. Different file this time.

<source lang="bash">cat /tmp/nub0mode_before > /proc/pandora/nub0/mode
cat /tmp/nub1mode_before > /proc/pandora/nub1/mode

rm /tmp/nub0mode_before /tmp/nub1mode_before</source>

This will restore your nub modes to what they were before, and delete the temporary files used to store them. You must save it as '''PND_post_script.sh'''.

=== Step 4 ===
Simply copy these files into the appdata folder of your program of choice! Now you're done. If you want to test it, drag these files into the appdata of a program that runs windowed (like [[Comix|Comix]] or [[Deadbeef|Deadbeef]]), so you can test with the mouse. Simply delete the files if you no longer desire their effects.

== Method: Switch between nub configurator presets ==

Hint from: [http://boards.openpandora.org/index.php?/topic/2860-tutorial-how-to-have-your-nubs-change-modes-upon-launching-of-a-pnd/page__view__findpost__p__118405 Caine]

=== Steps ===
* Start the nub configurator
* Create a profile for the setup you wish your application to use.
* Below, I'll assume a profile is created which is called joysticks which places both nubs in joystick mode.
* Create a file PND_pre_script.sh with this content:
** /usr/pandora/scripts/op_nubmode.py -s temp_profile -p joysticks
** This will store the current configuration in a profile called temp_profile and next will load the joysticks profile.
* Create a file PND_post_script.sh with this content:
** /usr/pandora/scripts/op_nubmode.py -p temp_profile -d temp_profile
** This will load the previously created profile temp_profile and will remove it afterwards.
* Simply copy the files PND_pre_script.sh and PND_post_script.sh into the appdata folder of your program of choice!

=== Advantage ===

Uses the GUI to easily create custom profiles without having to know where values are written to.

=== Disadvantages ===

* It is slower, uses some memory and writes profiles to NAND.
* If you want to avoid NAND-writes per launch and you always revert back to the same profile after launch then you can use static profiles without having to save and remove the current. E.g. something like:
** Before: /usr/pandora/scripts/op_nubmode.py -p joysticks
** After: /usr/pandora/scripts/op_nubmode.py -p Default

[[Category:PND]]
[[Category:Development]]
[[Category:Keyboard]]

PND nub modes

2012-01-16T18:00:39Z

Porg: /* Step 1 */

{{IntroNote | This page is a work in progress, the instructions in here may or may not work for you (They were copied from [http://boards.openpandora.org/index.php?/topic/2860-tutorial-how-to-have-your-nubs-change-modes-upon-launching-of-a-pnd/page__view__findpost__p__49157 here]. For an introduction to PNDs, see [[PND quickstart]]. }}

== Rationale ==
Why would you want to do this? Simple; at least one person has reported that, when playing a natively-ported FPS (like Duke Nukem or Quake, but not GoldenEye) on the Pandora, using the right nub as the mouse has proven to be more comfortable and less awkward. But switching nub modes manually is annoying; so let's have Linux do it for you!

== Tutorial ==
=== Step 1 ===
You must download sebt3's new [[pnd_run.sh]] installer and run it. Get it [http://sebt3.openpandora.org/pnd/pnd_run_installer.pnd here]. 
'''Note: This step is no longer required as of Hotfix 6 Alpha 1.'''

=== Step 2 ===
Open a text editor and copy/paste this:

<source lang="bash">cat /proc/pandora/nub0/mode > /tmp/nub0mode_before
cat /proc/pandora/nub1/mode > /tmp/nub1mode_before

echo "mbuttons" > /proc/pandora/nub0/mode
echo "mouse" > /proc/pandora/nub1/mode</source>

This will back up your current nub modes, then switch them; the left will act as the mouse buttons, the right will act as the mouse. If you'd like, you can substitute "scroll" or "absolute" (joystick) in, depending on how you like your nubs. But you must save this as '''PND_pre_script.sh'''. Save it wherever you'd like, you will be moving it elsewhere later.

=== Step 3 ===
Copy/paste this into the editor again. Different file this time.

<source lang="bash">cat /tmp/nub0mode_before > /proc/pandora/nub0/mode
cat /tmp/nub1mode_before > /proc/pandora/nub1/mode

rm /tmp/nub0mode_before /tmp/nub1mode_before</source>

This will restore your nub modes to what they were before, and delete the temporary files used to store them. You must save it as '''PND_post_script.sh'''.

=== Step 4 ===
Simply copy these files into the appdata folder of your program of choice! Now you're done. If you want to test it, drag these files into the appdata of a program that runs windowed (like [[Comix|Comix]] or [[Deadbeef|Deadbeef]]), so you can test with the mouse. Simply delete the files if you no longer desire their effects.

[[Category:PND]]
[[Category:Development]]
[[Category:Keyboard]]

PND management workflow

2012-01-15T23:52:32Z

Porg: Category:Ideas and proposals

== Whom it concerns ==

* Thinkers who oversee the Pandora software platform as a whole and on the long run (core team & others)
* Plus in particular the developers of:
** Launchers like: MiniMenu, XFCE Menu, quick text based launchers
** Package managers like: PNDStore, PanoramaMilky (I use "PanoramaMilky" to refer to "Panorama in UI mode milky test")
** Package metadata/override editors/tools (PND and OVR)

== Topic of this work group ==

Software packages are at the center of the Pandora, hence the overall way how to manage them are key to success of the platform's usability and popularity.

Currently the different aspects of managing and using PNDs are spread over a patchwork of different tools and workflows, and some aspects are yet not covered at all.

I now try to describe what is important from a user's point of view, what already exists (to my knowledge), what should be realized, and point towards possible gap-closing and synergies between existing solutions.

Disclaimer: Generally speaking, the patchwork per se is nothing bad. Openness is the principle of the Pandora, and it should by principle be always possible for a tool to cover/handle just a very small and specific task. Nevertheless from the user's perspective it is appreciated to have as little steps as necessary for common tasks in (at best) one uniform environment.

== Follow up ==

The issue was first brought to attention within the [http://boards.openpandora.org/index.php?/topic/5636-usability-of-package-management-pnd-coordinating-related-development-efforts/ developer forum].

It is discussed over there, and resulting actions, outcomes and developments are noted here in a structural form within the wiki-page into the SPECIFIC sections!

If necessary mark your addition with author and date in this markup format:

<nowiki>: A comment. If Daytime is given, state as UTC. -- Author YYYY-MM-DD HH:MM UTC</nowiki> 
<nowiki>:: Further nested comment without a date only and no daytime. -- Author YYYY-MM-DD</nowiki>

Note: The double dash helps to quickly skip through the wiki page for authors and their comments.

----

If your addition is large, please create only a short inline summary, and link the full content to a new page! (or: use <code><nowiki>{{HideableNotes|your text here}}</nowiki></code> to {{HideableNotes|hide your text}})

The content of the wiki describes aspects, which sometimes implicit bug reports, feature suggestions, etc, but not explicitly written and some of them yet not reported to the issue tracker.

Please be autonomous enough, to realize your responsibility for your own. I spent hours brainstorming and writing this memo, even further dividing the tasks would overburden me. See it as a whole, co-ordinate your efforts (in the thread as this is "meta"), and only then slice it up on single issues. Thanks!

== Main needs around handling of software packages (PNDs): ==

* Discover
* Install ( + Update + Remove)
* Test
* Tag
* Launch
* Overview

== What is meant by this? How are they related? ==

=== Overview ===

The possibility of overview (filtering / sorting) can aid in all other tasks.
The data source for "overview" is the metadata included in the PNDs plus the overrides included from OVRs (or other yet not developed over-ride/lay methods).

=== Test ===

Currently, after installing new apps which you want to test, you have to find them as "the needles in the haystack" among the already installed apps, instead of a convenient mode, in which you can only run "new apps".

One might say: Just remember an app's name and find it from the "All" category. But what if you installed 3-5 new apps or even more … already a bit more complicated then!

If the PND framework would keep track of how often apps have been launched (or just a simple "ran-once" flag), this would provide a data basis for certain display modes like "Show new apps" or "Sort by usage frequency" in "overview" or "launch" applications.

=== Discover ===

Works quite good through:
* Various information media related to OpenPandora like forum announcements, PandoraPress, various feeds.
* Informal ways like chats, forums.
* Formal catalogues / databases like the open handheld archives, appstore, repo), the latter being well suited for integration into software (machine readable). This medias especially increase the chances for newcomers, which are yet un-featured in the information and informal medias! If a user finds a well sorted catalogue, his/her readiness for trying new applications rises!

Application name, description, icon, screenshots, categories deliver a good enough idea. Filter options like categories, or sorting actions like "most recent" help to narrow down the selection even more.

This aspect is already very mature on the Pandora!

What could be slightly improved: If "discover" and "install"/"test"/"remove" are integrated into one application, your system could systematically keep track of already tested and deliberately removed applications as "uninteresting", and hide them in your further "disover" process! Sparing you a lot of time/attention seeing items again and again, which you already once found as uninteresting!

Right now, if you manually scan catalogues, you likely stumble across candidates, you already deliberately rejected, which steals you your time /attention. The only display mode which spares you this: Sort catalogues by "recently published", and thereby all new stuff is really new to you. But of course, all the display modes like, categories, tags, remain crowded with already seen stuff.

=== Install/update/remove ===

These 3 tasks must be hand-able within one environment!

At the Pandora beginnings, no tool existed, meanwhile tools came to the rescue!

I do not expect from the "launch" application (MiniMenu) to have "install/update" abilities, but at least have the "remove" ability, to facilitate "test" process. "Launch app, test wether you like it, quit app" and then "remove" right away if you don't like it!

MiniMenu: Shall be able to delete a PND application (if on remove-able media).

PNDstore and PanoramaMilky handle Install/update/remove quite ok already.

PNDstore: Shall remember default installation locations better, as PanoramaMilky already does.

After running a "scan for updates" the manager shall have the possibility to update all or only certain selected apps. (equivalent to iOS Appstore app).

=== Tag ===

The "tag" process overrides the metadata fields supplied in the PND manifest with the fields the user finds better suitable (i.e. file an item under another subcategory, add a custom note, etc), which later aids "overview" and "launch" applications.

Right now there is neither a well-working workflow for "test an app, quit it, tag it" nor a mass-editor for tagging multiple apps according to your memories or notes.

The advantage of "test an app, quit it, tag it" is, that the user's memory of the tested applications is still fresh, hence the tagging is easy to make and appropriate.

: There is currently no tag concept associated with PNDs. It is possible to abuse notes for this purpose, but none of the tooling will really be able to do anything useful with it as there are no semantics specified for the fields. -- Caine 2011-10-10 12:53 UTC

==== MiniMenu - Test an app, quit it, tag it ====

Problem 1: After you ran an arbitrary app and quitted it, you do not return to your last position (bug #241). You need to find that app again first. And then go into submenus. And only then tag it.
Problem 2: After the override of ONE SINGLE app, MiniMenu currenty completely restarts, thus rescans **all** .PNDs and .OVRs! Only re-reading the affected PND + OVR would tremendously speed up.

If both problem 1 + 2 would get fixed the method "test an app, quit it, tag it" would practically work.

==== Mass OVR editor ====

A spreadsheet-like list with all apps, with the columns: icon, name, custom note, cat, subcat, possibly also summary/screenshot as obtained from repo-catalogue to refresh one's memory, where one can then quickly edit all the metadata of all apps to suit one's own sorting system better.

Caine already developed "OVR editor", and considers to realize such a "OVR spreadsheet editing mode". http://boards.openpandora.org/index.php?/topic/4201-ovr-editor-and-pnd-aware-application-launcher/

=== Launch ===

Your interface for launching apps. The data source for this comes from the PND files plus your OVR override files ("tag" applications).

Launch could be much more fine grained, please see the section on the possibilities of combining: Launch + overview.

Besides this some suggestions of improving existing features right here in this section.

==== Hotkey application launcher ====

Well known from many OSes, this feature would be fine within the Pandora too.

Triggered by hotkey working from everywhere or from menu/desktop entry -> text input with auto completion of installed apps -> launch.

I think that already exists. I just don't know which one's, and how to set the hotkey for it.

==== XFCE launch menu shall have meta trees "All apps" and "All games" ====

MiniMenu has an "All" category tree. The XFCE launch menu doesn't! Would be fine if it had one meta tree which "holds them all".

== Combinations ==

Many combinations of tasks are already described in one of the affected task "verb" sections. Some of these involve many others, and are therefore described below as combinations of "task verbs".

=== Discover + install + update + remove ===

Right now "discover", "install" and "test" are separate workflows.

PanoramaMilky very well unites "discover" + "install/update/remove".

: I think discovery could be improved in MilkyTest by allowing ordering packages by rating and showcasing random highly rated applications. Not sure how the showcasing would work with the UI, but it's something to consider'' -- B-ZaR 2011-10-10 05:41Z

: Discovery should be handled by browsing the apps in the repo along with their preview pictures to get an impression of the content. Sorting orders should include alphabetically, by rating, by author, and newly added (excluding recent updates). Also of note, we are essentially talking about CRUD operations on apps. Create (install), Read (run), Update (upgrade app/edit OVR) and Delete. I've always assumed these to eventually merged into a single application, though so far I omitted the OVR files in that vision.'' -- Caine 2011-10-10 12:33 UTC

PanoramaMilky: Would be cool if it could "launch" apps. You could "test" the app, then quit it. PanoramaMilky must then have the previously launched app selected so that you can immediately "remove" or keep it.

: Already planned, though I'll probably fork MilkyTest to create a more fleshed out UI under a different name. MilkyTest was always about testing milky-plugin. I'll post more on this to panorama's beta thread.'' -- B-ZaR 2011-10-10 05:41Z

:: I propose to make "Panorama in UI mode MilkyTest" a standalone PND. -- porg 2011-10-10 17:00 UTC

=== Launch + overview ===

Currently MiniMenu allows a filesystem like browsing with metaphors like tabs as categories / subcategories as subfolders within that tabs, and some generated meta categories like "All".

These additional display modes would help:

==== New meta category "Fresh", "By Date Added", "By Date Published" ====

This is for aiding the "test" process, particularly showing yet untested or fresh apps.

Implementation could be hard: As the PND has no central registry, but rather "certain files at certain places", which are scanned to then provide a "certain basis for certain launchers", the tracking of this dates or usage amounts must happen within that scanners/launchers, which must either have the "test" and "tag" abilities themselves, or must make that data available to those applications. Does anyone know what according data is tracked within MiniMenu?

==== Rating and/or favorite system. ====

Date source for "favorite" and/or "sorting" is provided by from your "tagging" (overrides). In addition the "launch" application may have its own methods to "rate" or "favor" applications. (Again this would be good for the approach: "Run app, test app, tag it".)

MiniMenu should show a tab "Favorites", which contains all apps, which are flagged as "favorite" or which have a rating above a certain treshold (i.e. on a scale from 1-5, all which are equal or higher than 4).

MiniMenu should show one tab "By rating", which contains all apps, sorted by rating (as sort key 1, and by alphabet as sort key 2).

If you navigate within the categories and sub-categories folders/tabs, a certain hotkey or menu command, should trigger the "favorite display" or "sorted display", which filters/sorts the contained items accordingly.

Pressing favorite hotkey first: Shows only favorites.

MiniMenu: Flawed tab display of sub-categories if they have a common string beginning
Pressing favorite hotkey again: Shows favorites on top of others.
Pressing favorite hotkey again: Disables favorite view mode, normal view again.

Pressing sort hotkey first: Sorted from best to worst
Pressing sort hotkey again: Sorted from worst to best
Pressing sort hotkey again: Disables sort view mode, normal view again.

==== MiniMenu - Improvements of existing functionality ====

There are many MiniMenu related bugs to be resolved!
Just search the [http://bugs.openpandora.org/?string=MiniMenu bugtracker for MiniMenu]

[[Category:Ideas and proposals]]

Multisite username check

2012-01-15T23:52:13Z

Porg: Category:Ideas and proposals

This is a suggestion by [[User:Porg|Porg]]. Participation is welcome!

In the user registration process at the various Open Pandora related sites (board, wiki, repo, bugtracker, …) [[User:Porg|Porg]] suggests to display the following hint:
----
'''Before registering your username''' here, you can run the [http://usernames.openpandora.org/check Pandora sphere username checker], which tests whether the username already exists within any other OpenPandora [http://usernames.openpandora.org/sites related sites]:
* '''As a courtesy to other users''', in order to not take their name away on other sites.
* '''For your own convenience''', to achieve a uniform nickname on all the OpenPandora sites, as a new arriving community member.
----

== ToDo ==

# Which Open Pandora relates websites (with user registration) are there? '''Anyone''' please add the URLs to the list below.
# Which site operators are willing to cooperate? '''Site operators''', please confirm your readiness, by writing your name plus short note next to the URL. Requirements for participating site operators:
## Offer a software interface (API) for testing whether a username exists at your site.
## Display the hint and link to or embed the checking service (iframe) into the registration page/process of your site.
# We need a web developer to create that multisite username checking service. '''Developer volunteers''', please participate in the [http://boards.openpandora.org/index.php?/topic/6068-suggestion-open-pandora-scene-multisite-username-checker/ discussion process], or enlist your dedication right below.

== Sites ==

URL of a Open Pandora related website which uses user registrations/logins + site operator(s) (nick)name and confirmation of participation + optional remarks:

===== Official Sites: =====

http://boards.openpandora.org/

http://repo.openpandora.org/

http://apps.openpandora.org/

===== Unofficial Sites: =====

http://pandorawiki.org/

http://gp32x.com/board/

http://pandorapress.net/

http://openhandhelds.org/

===== Alternate Language Sites: =====

http://wiki.openpandora.de/ (German)

http://forum.gp2x.de/ (German)

http://openpandora.jp/ (Japenese)

http://openpandora.info/ (russian)

http://www.opgaming.com/ (Italian)

http://openpandora-france.forumactif.net/ (French)

http://forum.gp2xtr.com/ (Turkish)

== Developers ==

Developers, who are willing to realize the multisite username checking service, please enlist your (nick)name and confirmation of participation plus optional remarks here:

[[Category:Ideas and proposals]]

Libpnd hub

2012-01-15T23:21:08Z

Porg: /* Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file */ Link to Wikipedia about Zenity GUI. Small typo corrections. Reordering related list items.

:''Basic users will be more interested in the page [[Introduction to PNDs]]''

{{TOC limit|limit=3}}

{{split section|To much text, a lot of things could be outsourced to dedicated shorter articles}}

=Overview=

[[libpnd]] is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)

[[libpnd]] thus is a collection of:

* handy system code that hopefully is reusable - IO functions, CPU clock setting, etc.
* applications for supporting the Pandora's unique features, such as ''pndnotifyd'' for auto-discovery of PXML and .pnd applicatons
* libraries for support of the .pnd and PXML systems; i.e.: for locating, executable, mounting and unmounting PXML-directory and .pnd applications, loading PXML and handling overrides
* hopefully reusable code for support of these things; i.e.: a rudimentary but useful config-file parser, rudimentary singly-linked-list container, etc.

It will also include utility functions for setting the CPU clock, reading GPIO inputs without depending on SDL, and other handy bits.

'''You can, nay, are required to - contribute to libpnd!'''

==Design considerations and philosophy==

While much of [[libpnd]] is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..

* simplicity - just work right, configuration not generally needed
* obviousness - work as one would expect for this sort of device; i.e.: the user assumes something will work a certain way, and it does
* like other guys - as an extension of the prior point, we have tried to follow UNIX spirit and provide reusable small tools to do the work those bits can be leveraged, but further tried to follow the spirit of other consoles. So while the device is a powerful little computer, it is probably going to be used by gaming and retro enthusiasts and so we color some of our decisions that way. (i.e.: consider that a PS2/xbox/PSP/etc will have save-game or data management as a separate application, for instance. If thats the best multi-million dollar companies can come up with over decades, well, its not so bad for us to fall back on!)
* not over-defined; libpnd and PXML try to define a bunch of things, but we also do not _over define_; we try to lead by providing examples and styles, and while we have designed ahead for many things, we have also not nailed a lot of that down too early. It is better to be simple and shipped, then complex and a mess.. adaptable rather than scary.

The library is of course broken into parts:
{|class="wikitable"
!Part!!Comment
|-
|include||include these files to make use of the lib
|-
|lib||the code that produces the lib
|-
|test||mini tools to test various pieces of the lib in isolation
|-
|bin||test tools - tools for testing the lib as it is developed, not anticipated to be used by many
|-
|testdata/||for testing /etc/pandora; will contain 'conf' dir, for example
|-
|apps/||actual applications people may use, such as [[pndnotifyd]]
|-
|}

For now though, here are a couple notes about the design.
* it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it). I have gone out of my way to limit external references so that bindings are easier to make.
* contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.
* I have tried to keep the API relatively simple and am faking some OO like data hiding to try to keep dev noses out of structures that are subject to change. i.e.: functions for list management and node access are provided, don't dig into the void* cast structs, or you could get burnt.
* the API should be pretty stable; so far very few user-code changes have ever been needed.. lib internal changes should be binary compatible.
* As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself
* As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)
* The lib works pretty well, but there is room for improvement internally; it won't hurt my feelings for you to suggest improvements, and I'm sure we would all be grateful for any patches you provide. We've _started_ this library, but by no means wish to carry it alone!

==Opportunities for improvement==

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

* Better ISO lang handling ... due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)
* Validation of files when they're loaded
* An actual parser of PXML metadata

[[New PND format | This page describes a proposed new PND format.]]

==License==

libpnd (including all the apps etc) are released under the LGPL (ie: so there should be no encumbrances that prevent linking to commercial applications.):

GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999

==Obtaining the library==

libpnd is in the Official Pandora GIT repo: [http://git.openpandora.org/cgi-bin/gitweb.cgi]
To obtain yourself a copy, use something like:
<pre>
git clone git://git.openpandora.org/pandora-libraries.git
</pre>
Thats all you normally need. For copy-paste from the private Wiki sake, heres what I had before:
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:

<source lang="bash">
mkdir libpnd
cd libpnd
git init
git remote add libpnd ssh://foo@git.openpandora.org/srv/git/pandora-libraries.git
git push libpnd master
</source>

==Building the library==

Standard 'make' should be sufficient here; pull down the directory from the GIT, cd into it, and run make. Thats it.

Note that the make default target is 'everything', which will emit:
<source lang="bash">
libpnd.a - the static linked version of the lib
libpnd.so.1.0.1 - the dynlinked version
libpnd.so.1 - the stub for the shared lib; i.e.: apps should link against libpnd.so.1 and not the 1.0.1 over-specific version
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin
</source>

There are a few additional make targets, however.

{|class="wikitable"
!Target!!Description
|-
|make clean||wipes out the object files, the bin files, and *~* (emacs backup files), empties some of the deploy stuff, etc. Do this before committing to GIT or we will beat you with sticks.
|-
|make deploy||populates the deploy/ directory, which is what is used inthe shipping images; i.e.: testdata/conf includes test configs, while deploy/etc/pandora/conf includes the configs we ship with. This
|-
|make||will copy over some of the libs and binaries and such.
|-
|make pnd||create a few sample pnd files for testing the lib on an x86 machine
|}

==Included Applications==

===pndnotifyd===

Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need [[pndnotifyd]], though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)

===pndvalidator===

Is mostly a skeleton right now; in the future, it is hoped it will inspect a PXML.xml and then check to ensure the referenced assets are present; the goal to validate the PXML.xml is spec compliant, and the resulting application would be useful.

===discotest===

One of the test tools; it essentially runs an auto-discovery to list off the found apps (be they PXML.xml dir apps or .pnd files), and can dump various data or invoke one or other little tasks; used to test lots of
bits of [[libpnd]] as it was developed.

===rawpxmltest===

Reads a given PXML.xml and spits out some of the fields found within.

===Test tools===

See the test/ dir in the libpnd source for assorted goofy little test apps used for testing bits of libpnd over time. They also may serve as source examples for using some of the APIs. They're old and shoddy probably too.

==How does it work?==

This is just a quick summary to save you guessing by reading [[PXML_specification|this whole document]].

In essence, libpnd includes lots of real code, but in many places it passes heavy lifting off to shellscripts. This is both handy because the scripts are easily modified without recompilation, and further extends our design goals of making the library bindable to any other language.

Remember, PXML.xml directories are just as executable/mountable as .pnd apps.

So while libpnd is mostly straight-C and so easily bound to python or perl or whatever, libpnd itself invokes many scripts. Those scripts can be directly used by other applications, including other shellscripts.. so libnd functionality can even have bindings in other scripts. This is very flexible and powerful, and handy during debugging or SSHing into the Pandora, etc.

The application lifecycle goes like this:

* device is turned on
* during init, pndnotifyd is brought up and inhales the config giles
* pndnotidyd will attempt to auto-discover what PXML.xml directory apps and .pnd-file apps are in the configured searchpaths
* pndnotifyd will set up filesystem watches on the directories in the notify searchpath; if any of those directories are touched, pndnotifyd will wake up and re-auto-discover .. possibly removing .desktop entries or creating new ones. (i.e.: you drop a new app into the app searchpath, or remove one, or mount an SD card, etc. This is how appications immediately show up or vanish from the window manager desktops.)
* a libpnd aware launcher can execute applications direct (using libpnd)
* a libpnd unaware launcher can execute applications via the .desktop standard system; pndnotidyd will emit .desktop files as needed.
* when libpnd or a .desktop file need to execute an application, they do it via pnd_run.sh (which may be leveraged by other applications, but they hould use libpnd if they can instead, for utmost compatiblity down the road.) pnd_run.sh does the mount of the ISO, runs the actual execable and so on, as directed by libpnd or the command-line args from the .desktop. pnd_run.sh will clean up after everything as well.

So it all works like magic, but it is not that complex a system once you've got the hang of what all is going on.

application → libpnd → shellscripts → system

==FAQ: IF you want to make files visible to the apps, do you have to modify the pnd?==

No. When apps write back to themselves, the writes go to their /pandora/appdata on the SD that houses them. The next time the app reads a file in its directory, the OS will ensure they get the newer file, which is the one in the appdata.

Likewise, you can just drop a file into the appdata and the app will see it.

The app doesn't know about appdata and its pnd file.. the OS and libpnd take care of all the magic.. the app sees one directory, but the reality is there is magic merging going on behind the scenes.

==Assumptions about the filesystem and Configuration==

Note that for libpnd to work, it makes certain assumptions about the filesystem and config files. Since libpnd was developed with the images it should work for the Pandora .. but just dropping libpnd onto another Linux distribution and it won't likely 'work out of the box'. Certain config files will need to be set, and certain conventions followed.

===Searchpaths===

libpnd was designed so that most everything is configured in files, and that these files should be easily hackable and easily overriden, without compromising the machine. It should be feasible to add a config file to an SD card, have it take over if available when required, and then 'undo' those configs simply by removal of the SD card and rebooting.

To facilitate this design goal, all config files are 'sought' using a search-path system.

Developers should be mindful of using the libpnd APIs so this behaviour is inherited to interested applications; developers could also reuse the logic for searching for files, if they find it useful.

Searchpaths are colon-delimited list of paths, searched left to right.

ex: foo:bar:/my/baz means to look for a given file in 'foo', then in 'bar', then in '/my/baz'.

The standard config files have a default searchpath, and those config files will define further searchpaths for scripts and such the system uses. This makes the system highly flexible -- default scripts are included, but can be overridden by dropping the right named script on an SD card, or by altering a config file.

See the example config files below for example searchpaths -- i.e.: how pndnotifyd searches for pnd_run, etc.

===Notification paths===

The 'apps' config includes a searchpath that specifies the sub-paths to be 'watched'. Various watch mechanisms exist for various filesystem types, but over the course of Pandora development (various kernels, various k-modules, various DM and WM's, I found the included system most stable, though not most current. After a final device image is settled on, it might be time to alter the notification system, but it should not impact the libpnd API.)

Anyway, watches are placed upon the paths defined, and if anything in those paths changes, the auto-discovery code is kicked off to seek our PXML.xml and .pnd type applications in the search paths.

Note that searchpath and notifypaths are different (and usually very similar, but have the option to be very different.)

===Config files===

libpnd includes a generic simple config file parser and assumes the presence of a few config files. It also includes defaults
so if a config is missing or broken things should work.

In general, Pandora specific config files should be located in:
<pre>
/etc/pandora/conf
</pre>

The config files are:
{|class="wikitable"
!!File!!Description
|-
|conf||this file is generally _not_ included with the Pandora and left to default; its job is to define the basic default searchpath for config files, so should you wish to override things entirely, you may need to alter this file. i.e.: If you wish to switch to test config files on SD or in /tmp, instead of using any other conf files .. you can create this guy. This provides a mechanism to short circuit the entire conf system.
|-
|apps||this config file defines auto-discovery and other application bundle parameters
|-
|desktop||this config defines "dotdesktop" .desktop and FreeDesktop integration paramters -- example is where to spit out icons or .desktop files from discovered PXML.xml or pnd applications
|-
|categories||this config maps PXML.xml spec based categories to FreeDesktop standard categories; in this way a PXML based applicatoin can show up in the appropriate categories of a WM that does not use libpnd
|}

====conf File====

No default is included with the distribution.

The default search path is reasonable and assumes we want the official /etc/pandora/conf near the end, with checks to the SD cards for overrides first. (Likely most people will not override, so the canonical location will be used 99.9% of the time.)

<pre>
#define PND_CONF_SEARCHPATH "/media/mmcblk0p1/pandora/conf:/media/mmcblk1p1/pandora/conf:/etc/pandora/conf:./testdata/conf"
</pre>

The key for override is:

<pre>
#define PND_CONF_KEY "conf.searchpath" /* if not found, use PND_CONF_SEARCHPATH */
</pre>

Which suggests using something like this.

<pre>
[conf]
searchpath /foo/bar:/baz/bing
</pre>

====desktop File====

<pre>
# Open Pandora
# Desktop configuration

[dotfiles]
#(~/Desktop for xfce, /usr/share/applications for WMs that actually follow spec)
dotdesktoppath ~/Desktop/ # path for pndnotifyd to spit .desktop files into (run as root)
iconpath /tmp # path for pndnotifyd to drop icons into (can be same as .desktop if WM permits)

[launcher]
# if hupscript is commented out entirely, pndnotifyd will not try to find/run the hup
# if it is uncommented, pndnotifyd will attempt to invoke the hupscript after emitting .desktop files
# (the hupscript exists to hup the WMs to redisplay .desktop apps)
#hupscript pnd_hup.sh
</pre>

====apps File====

<pre>
# Open Pandora
# Application configuration

[autodiscovery]
# searchpath is a list of paths (colon separated) in which to look for PXML.xml or .pnd-file applications
searchpath /media/*/pandora/apps:/usr/pandora/apps
# notifypath is a list of paths to monitor; if anything in those paths changes, the searchpath is rescanned
# note that for each path chunk, all current subdirs of that path are also watched)
notifypath /media:/media/*/pandora/apps:/usr/pandora/apps:./testdata/app?

# PXMLs may be overridden .. i.e.: overrides are a subset of PXML, where the values are copied over the full PXML
[overrides]
# searchpath to look for PXML overrides (which are named by the unique-id)
searchpath ~/pxml-overrides

# [pnd] defines where to locate the pnd support scripts, so the user may override pnd_run.sh without clobbering built in
[pnd]
searchpath /media/*/pandora/scripts:/usr/pandora/scripts
runscript pnd_run.sh
</pre>

====categories File====

<pre>
# Open Pandora
# dotdesktop configuration

# this config file maps 'PXML' categories to free-desktop standard categories
# i.e.: category 'Foo' could map to more standard 'Utility', thus making .desktop file
# emitting a more useful thing

# the standard listing of categories is:
# http://standards.freedesktop.org/menu-spec/latest/apa.html

# note that 'map' section in the config is _required_ for a match to be found; this
# is done to separate categories from (future) top-level directives

default Application;Utility;Network;

[map]
Development Development
Education Education
Games Game
Graphics Graphics
Internet Network
Multimedia AudioVideo
Office Office
Settings Settings
System System
Utilities Utility
</pre>

===SD card layout===

libpnd concerns itself with things in the 'pandora' root folder on SD. We agonized over this decision, but settled on this to avoid cases where someone with a 16GB SDHC card puts 50-million files with ".pnd" on them, and expects reasonable performance. Instead, applications for instance would have to be in:

<pre>
/pandora/menu -> apps that will go to /usr/share/applications and should show up in xfce menu by category
/pandora/desktop -> apps that will go to ~/Desktop and show up on user desktop as icons
</pre>

The following location is used by pmenu (and may get deprecated, but I've not discussed it with cpasjuste yet.)

<pre>
/pandora/apps
</pre>

i.e.: the searchpath for autodiscovery includes /media/*/pandora/apps (and desktop and menu now)

Also in the /pandora/ folder is a magic 'appdata' folder:

<pre>
/pandora/appdata
</pre>

When a .pndfile or PXML.xml dir get mounted, any writes back to the mounted area are put into appdata, with a subdir by the unique-id. i.e.: With the hypothetical MAME.pnd, it might update its config files after a user changes something, or create new files, or store hiscores or whatever. If it doesn't write them to [[NAND]], and doesn't want ot write them to /mame/some/dir, but instead record it to itself for whatever reason, it would go to /pandora/appdata/MAMEs-ID/ instead. The pnd or PXML.xml app area is never modified during a run, only the appdata. (But when an application reads its own path, it will pick up the appdata version of the file instead of the actual file. Then magic of union-type filesystems!)

Example:

If Myapp with unique-id foo.123 is mounted, then any write-backs are directed to..

/pandora/appdata/foo.123/

On the SD that hosts the application.

===NAND layout===

In addition to seeking applications in [[SD cards]], /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.

It might be a cool addition to put a user homedir into the searchpath as well, so [[NAND]] but user-homedir (for on-device browser downloads, say.)

==Command line tools and testing==

A number of scripts and tools are included or built with libpnd, to facilitate testing of the lib as its being developed and to assist in making .pnd files and PXML.xml files.

==PXML.xml and .pnd files==

On most platforms, applications are distributed as an executable and optional datafiles and likely an installer. The installers job is to integrate the application into the filesystem, as the transport mechanism itself is not executable and is considered temporary. In Windows an application might be installed into Program Files, while in Unix an application might be dropped into /usr/local/bin .. data files in various other places.

For the Pandora platform we wanted a very easy to use workflow -- download and run -- and also have a very different operating environment. With multiple SD cards available for expansion (and that space being highly desirable due to a smaller internal store) it is desirable to install applications to SD, and yet SD cards are by definition something users will wish to carry multiple of. With two slots, it could be quite a chore to install an application to SD1, its data to SD2, and then say have only one of them plugged in at a time, or switch which slot they're in, or any number of scenarios. i.e.: Installing onto a medium which may be present or not at any time is very different to how most operating systems work. So we made something new and awesome.

The PXML.xml and .pnd-file approach we came up with attempts to address these issues.

The goals:
* for the user, an application can be a single file download
* furthermore, there is no installation whatsoever, beyond dropping that single file into the right place on the SD card
* using the application should be easy -- stick in the SD card, and tap/launch on the icon.
* for uninstallation, delete the single file. Thats it, no fuss.
* for the developer, creating that single file should be easy to do
* for the system, performance should be high

Remember, an application can be a .pnd 'bundle' (single file containing all the sub-files), or a PXML.xml 'dir application' (an unpacked .pnd esentially.) '''BOTH PXML.xml-dirs and .pnd's ARE EXECUTABLE.'''

pndnotifyd will auto-discover PXML.xml in a directory and consider that an application, emitting a .desktop file, just as well as a .pnd file. i.e.: This can be hand for development or users. Remember that a mounted PXML.xml dir still redirect write-backs to the /pandora/appdata directory, just like a full .pnd application. They are treated the same!

===What are PXML.xml and .pnd files?===

PXML.xml is a file describing an application
A directory containing a PXML.xml _is executable_
A .pnd file is the packaged up version of the directory that is executable.
i.e.: a PXML.xml in a directory is just as executable as a .pnd representation of that directory.

Example:

<pre>
mkdir OutcaST
cp outcast.bin OutcaST/
cp PXML.xml OutcaST/
# at this point, the OutcaST directory is now discoverable and executable
</pre>

pnd_make.sh -this -that OutcaST outcast.pnd
# at this point, outcast.pnd is executable (as is the OutcaST directory), so upload outcast.pnd to the Open Handhelds Archive and let people enjoy!

===A note on including shared libs===
A philsophy for packaging that I am advocating is to 'just make applications work' -- avoid dependancy trees.

Some guidelines:

1) you can depend on shared libs included with the firmware to always be there

2 you should include any shared libs you need for your app, that are not in the firmware (yes, this increases app size a little bit, and potentially makes for duplication among apps that use the same shared libs)

3) if a shared lib becomes desirable in the firmware, it can be added there as a firmware patch easily (this has the advantage of gradulaly updating the entire user based, and apps easily saying 'we depend in firmware version X', rather than making for pnd-dependnacies and the equivilent of 'dll hell'

4) You'll have to be careful in linking your application to ensure that the shared libs you are including in the pnd/PXML-dir are to be locatable by your binaries. ie: stick them in a 'lib/' dir in your bundle, and stamp your binary with a library-path './dir/' so they can be found, say. More later.

===Future idea: pnd's for containing system-wide shared libs===

This is something we've bounced around for quite awhile, but not committed to. As it keeps coming up I thought I'd put some notes here in public.

It is possibly desirable to make a special searchpath that is discovered during machine boot, and any pnd's found there are automatically mounted (and left mounted) into a special path (say /usr/local/pandora/lib or somesuch.) This way, collections of handy utilities or shared libraries could be distributed as a pnd, and become available in consistent locations. If 10 applications need a shared lib, and don't want to duplciate it in each of their pnd files, this could be an approach.

I tend to think it is best avoided, however, since it complicates the user experience -- we end up with pnd depandancies, and apps nolonger about to 'just work', and apps that did work and 'suddenly break' when other files are altered. The philosphy we're going for with pnd files is 'drag and drop' -- user downloads a pnd file, and it works.. a self contained application, nice and easy. We start complicating the dependancies, and it turns into 'dll hell' as seen on other platforms.

That said, it is _not_ difficult to add into the existing system and design; we've been mulling it over, but it is best avoided for now. rather than complicate the system up front, let us try to get a functional and as lightweight-as-possible system on the uptake, gather some usage data points and then worry about upgrades :)

===File format - PXML.xml / PXML Specification===
See the [[PXML_specification|PXML specification]]

Alternatively the spec is included in the docs/ directory of the libpnd distribution, though the wiki version linked above should be considered cannon.

A note on history; the PXML spec was originally created by EvilDragon, and went through a number of revisions as suggestions came in; as these things are wont to do, the target was ever moving and the scope and meaning of PXML changed so at some point a more strategic approach was needed. dflemstr took it upon himself to help recode some of the parse and re-evaluate many of the PXML decisions and hence was born the PXML-version-2 spec.

===File format - .pnd files===
The pnd file format is pretty straight forward, though most will interact with it through the included (or community supplied) tools.

Basically its just an ISO file (or other filesystem type) with a PXML.xml and an optional PNG icon appended. (example: cat appfolder.iso app.pxml icon.png > app.pnd) For ease of discussion, I refer to ISO but in fact you coudl be using squashfs or other types.

The ISO filesystem portion of the file can include anything the developer wishes, as long as it includes a PXML.xml in its root file and an executable somewhere in there. It can also include images, audio files, data files of any kind. It can be small or large.

Yes, the PXML.xml is included in the ISO portion (in the root directory), and also appended to the end of the .pnd file (for _convenience_ .. it is very easy and fast to locate in this position; we can backseek into the ISO to find the PXML, but if its a 500MB ISO it could take awhile. Hence, we append it and can find it in one seek.)

'''NOTE: The naming of the PXML.xml file is important! The name is case sensitive and must be "PXML.xml", nothing else!'''

This simple format makes it possible to easily create .pnd files with the default utility's of most operating systems. Further, it is a fairly fail-safe system -- the PXML is appended, but is also included within the ISO image part of the file so if the appended-PXML is ever lost (unpack and repack poorly, say) the system will still work (the PXML inside the ISO can be found easily, even without mounting the ISO _as_ an ISO, since it is a plaintext uncompressed image format.)

Manually creating a .pnd (or even a PXML) is a pain so there will be a few helper scripts or maybe even a gui app out when we launch.

Included with libpnd are some scripts to create PXML and pndfiles, though it is expected people will create handier utilities. See the tool section of this wiki for some details.

Question from the gp32x forum regarding confusion of PXML location -- remember that in general most developers will keep a directory that represents the .pnd or PXML-dir application. Their makefile/build-process will drop the executable(s) into that directory, which inludes a PXML.xml description of the application, and possibly an icon (and whatever all else they wish.) To build the .pnd file, a script (say) is used which compresses all this into the pnd format (including appending the PXML.) So yes, the PXML is in two places in the .pnd file and one place in the source directory. You'll get used to it ;)

Rationale --

Several iterations of pnd files have been considered, from zipfiles to cramfs to other formats, to putting in a key/value set of information tags in the file, to table-of-contents indexes, to any number of options to help performance, and so on. In the end we went for a good overall and simple solution and dropped getting fancy -- PXML.xml can be extended to define the type of the file if it cannot be magic'd, so we could using other filesystem types in the future (and this is why people should use libpnd rather than rolling their own solution.) For now however, pnd files are ISO files with the PXML.xml appended and an optional icon. This keeps the PXML and icon easy to locate, and yet a easy file format.

====Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file====

These are guidelines to make pnd-files 'well behaved', and to help move towards a consistent pnd structure.

* Always include your icon png-file and PXML.xml file in the _Root_ of the pnd-file; this is for reasons that folks may well unpack the pnd-file, and then repack it; in doing so, if the icon and PXML.xml (normally appended to the .iso to become a .pnd) will be lost, unless the user or tool is being careful. Thus, it is wise to include them within the .iso, to make things so the iso is the entire pnd application, in unpacked form.

* Use a 'reasonably unique' unique-id of course (to identify your application.) This is used for many internal uses, so uniqueness is pretty wise.

* Use an 'application relevant' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.

* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!

* Try using rudimentary [http://en.wikipedia.org/wiki/Zenity Zenity] scripts to pop up imporant pre-run information to the user via the GUI, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line Zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened

* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.

* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)

* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.

* For data that is not kept in your appdata directory, try to keep it local to the current SD _or_ better still, search both SD. ie: libpnd uses a basic but really handy system for iterating across a list of directories (including glob type expansion); so you can tell it something like /media/*/foo:/tmp and it'll check every mounted device (including both SD slots) in the 'foo' directory, as well as /tmp; you can have it call your code as it looks through, or you can ask libpnd to find a file for you and report where it was found, across all your searchpaths; you don't have to use libpnd's code to do it, you coudl write oyur own (using libpnd as an example if you need the help), as its pretty easy to build (20 lines of code maybe?) Anyway, the trick is to be multi-SD aware, and bonus marks for handling if theres a USB mounted drive etc as well. (Example; I coded minimenu so that when it caches out a preview picture, it checks for free space first, and tries first on the same SD that the pnd is mounting from, and then across a searchpath of alternate locations to cache to; this way the user can customize the caching, and it can be on various devices.)

====What filesystem types can be contained within a pnd-file?====

The pnd container can really contain a large variety of filesystem types; day-zero we're aiming for ISO since it is simple, easy build across every major OS, and fast to use. But it is not the only supported filesystem type, and more should be added all the time. (Possibly '-auto' can be added to pnd-run and it'll "just work" for dozens of types!)

A compressed filesystem type has always been desirable for file sizing reasons, though it potentially impacts performance (depending on the application operation really.)

Supported types (not an exhaustive list!):

* ISO
* squashfs

===Creating pnd files===

The [[PND quickstart]] page contains this information.

===PXML overrides===

There are a couple of ways to effect an override of the PXML, without modifying a pnd-file.

===="In-path" override files: .ovr====

The library automatically imports a limited number of overrides from a conf file that can be located in the same location as its matching .pnd file is.

For instance, if /pandora/desktop/awesomegame.pnd exists, then libpnd will automatically also search for /pandora/desktop/awesomegame.ovr

Some menu systems will also be smart enough to watch for an icon override -- /pandora/desktop/awesomegame.png -- and if present, to use it; 'minimenu' (mmenu) is aware of that, as is pndnotifyd daemon when emitting .desktop files. Likely pmenu will also be updated. In effect, the user can override the icon, category and other attributes of the pnd, without needing special tools or to alter the system.

An .ovr file must be named identically to the pnd-file, excepting the 3 character file extension.

NOTE: Given that a pnd may emit multiple applications from its PXML.xml, the ovr will have to be aware of this so it can override the correct application(s) within the pnd. Some menus and information tools will display the application list with 'subapp number' to assist identification. minimenu shows the subapp number in the detail panel, for example. In the case where a pnd-file has only one contained application, that is subapp-number zero. For any additional subapplications, increment by one .. but it can be tricky to know which app is which subapp number. (A careful eye will notice the .desktop filename includes the subapp-number after the pound sign .. foo#3.desktop is subapp_number 3.)

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 note text line 1
</source>

====PXML override file -- currently unsupported====

PXML.xml files can have any number of their elements over-ridden by user preferences.

The design goal here was to make it so user-preferences could alter the impact of the PXML.xml in any way, but without requiring the actual PXML.xml in the .pnd (and within the ISO therein) to be altered (could be a 500MB ISO after all!), and further, for these changes to persist. Consider than an SD card could be removed and inserted into the other slot, or the app could be removed entirely and come back another day, or other scenarios.

As such, the PXML-overrides are kept in NAND in the user homedirectory (See the config files to find out where.)

libpnd includes functions to pull in PXML, and also functions to then look for and merge in overrides. It is not always done since you may wish to inspect the PXML or the overrides, so the developers job is to do as they see fit -- pull the XML, and likely also pull in the overrides.

At this time I'm not sure if people will ever use overrides, but the system has been built in should it be needed.

===Included shellscripts to generate files and other sundry duties===

====genpxml====

This tool can spit out a basic but correct PXML.xml, faking up a halfway-useful unique-id in the process. It might be handy in saving you writing up a PXML.xml from scratch.

====pnd_hup.sh====

pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out whom to HUP.

====pnd_make.sh====

This is one of the great ones :)

Given a directory with a PXML.xml (see genpxml above) and an executable and any other goo you want in there, this script will spit out a .pnd file you can execute or distribute as an application.

====pnd_run.sh====

This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it dorectly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.

==Auto-discovery of applications==

TBD.

==Integration with FreeDesktop .desktop systems==

===dotdesktop (.desktop) files===

===Icons===

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.

==APIs==

Feel free to just go read the .h files; I have tried to comment liberally :)

===Setting and Getting the CPU clock speed===

===Device paramaters - brightness, etc===

===PND files, exec and mount===

===Application discovery===

===Config file parsing===

===Boxing, the singly-linked list container===

===Directory watching===

===Logging api===

[[Category:Development]]
[[Category:PND]]

Libpnd hub

2012-01-15T23:09:06Z

Porg: /* Creating pnd files */ Corrected erroneous wiki markup of headline

:''Basic users will be more interested in the page [[Introduction to PNDs]]''

{{TOC limit|limit=3}}

{{split section|To much text, a lot of things could be outsourced to dedicated shorter articles}}

=Overview=

[[libpnd]] is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)

[[libpnd]] thus is a collection of:

* handy system code that hopefully is reusable - IO functions, CPU clock setting, etc.
* applications for supporting the Pandora's unique features, such as ''pndnotifyd'' for auto-discovery of PXML and .pnd applicatons
* libraries for support of the .pnd and PXML systems; i.e.: for locating, executable, mounting and unmounting PXML-directory and .pnd applications, loading PXML and handling overrides
* hopefully reusable code for support of these things; i.e.: a rudimentary but useful config-file parser, rudimentary singly-linked-list container, etc.

It will also include utility functions for setting the CPU clock, reading GPIO inputs without depending on SDL, and other handy bits.

'''You can, nay, are required to - contribute to libpnd!'''

==Design considerations and philosophy==

While much of [[libpnd]] is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..

* simplicity - just work right, configuration not generally needed
* obviousness - work as one would expect for this sort of device; i.e.: the user assumes something will work a certain way, and it does
* like other guys - as an extension of the prior point, we have tried to follow UNIX spirit and provide reusable small tools to do the work those bits can be leveraged, but further tried to follow the spirit of other consoles. So while the device is a powerful little computer, it is probably going to be used by gaming and retro enthusiasts and so we color some of our decisions that way. (i.e.: consider that a PS2/xbox/PSP/etc will have save-game or data management as a separate application, for instance. If thats the best multi-million dollar companies can come up with over decades, well, its not so bad for us to fall back on!)
* not over-defined; libpnd and PXML try to define a bunch of things, but we also do not _over define_; we try to lead by providing examples and styles, and while we have designed ahead for many things, we have also not nailed a lot of that down too early. It is better to be simple and shipped, then complex and a mess.. adaptable rather than scary.

The library is of course broken into parts:
{|class="wikitable"
!Part!!Comment
|-
|include||include these files to make use of the lib
|-
|lib||the code that produces the lib
|-
|test||mini tools to test various pieces of the lib in isolation
|-
|bin||test tools - tools for testing the lib as it is developed, not anticipated to be used by many
|-
|testdata/||for testing /etc/pandora; will contain 'conf' dir, for example
|-
|apps/||actual applications people may use, such as [[pndnotifyd]]
|-
|}

For now though, here are a couple notes about the design.
* it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it). I have gone out of my way to limit external references so that bindings are easier to make.
* contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.
* I have tried to keep the API relatively simple and am faking some OO like data hiding to try to keep dev noses out of structures that are subject to change. i.e.: functions for list management and node access are provided, don't dig into the void* cast structs, or you could get burnt.
* the API should be pretty stable; so far very few user-code changes have ever been needed.. lib internal changes should be binary compatible.
* As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself
* As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)
* The lib works pretty well, but there is room for improvement internally; it won't hurt my feelings for you to suggest improvements, and I'm sure we would all be grateful for any patches you provide. We've _started_ this library, but by no means wish to carry it alone!

==Opportunities for improvement==

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

* Better ISO lang handling ... due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)
* Validation of files when they're loaded
* An actual parser of PXML metadata

[[New PND format | This page describes a proposed new PND format.]]

==License==

libpnd (including all the apps etc) are released under the LGPL (ie: so there should be no encumbrances that prevent linking to commercial applications.):

GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999

==Obtaining the library==

libpnd is in the Official Pandora GIT repo: [http://git.openpandora.org/cgi-bin/gitweb.cgi]
To obtain yourself a copy, use something like:
<pre>
git clone git://git.openpandora.org/pandora-libraries.git
</pre>
Thats all you normally need. For copy-paste from the private Wiki sake, heres what I had before:
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:

<source lang="bash">
mkdir libpnd
cd libpnd
git init
git remote add libpnd ssh://foo@git.openpandora.org/srv/git/pandora-libraries.git
git push libpnd master
</source>

==Building the library==

Standard 'make' should be sufficient here; pull down the directory from the GIT, cd into it, and run make. Thats it.

Note that the make default target is 'everything', which will emit:
<source lang="bash">
libpnd.a - the static linked version of the lib
libpnd.so.1.0.1 - the dynlinked version
libpnd.so.1 - the stub for the shared lib; i.e.: apps should link against libpnd.so.1 and not the 1.0.1 over-specific version
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin
</source>

There are a few additional make targets, however.

{|class="wikitable"
!Target!!Description
|-
|make clean||wipes out the object files, the bin files, and *~* (emacs backup files), empties some of the deploy stuff, etc. Do this before committing to GIT or we will beat you with sticks.
|-
|make deploy||populates the deploy/ directory, which is what is used inthe shipping images; i.e.: testdata/conf includes test configs, while deploy/etc/pandora/conf includes the configs we ship with. This
|-
|make||will copy over some of the libs and binaries and such.
|-
|make pnd||create a few sample pnd files for testing the lib on an x86 machine
|}

==Included Applications==

===pndnotifyd===

Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need [[pndnotifyd]], though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)

===pndvalidator===

Is mostly a skeleton right now; in the future, it is hoped it will inspect a PXML.xml and then check to ensure the referenced assets are present; the goal to validate the PXML.xml is spec compliant, and the resulting application would be useful.

===discotest===

One of the test tools; it essentially runs an auto-discovery to list off the found apps (be they PXML.xml dir apps or .pnd files), and can dump various data or invoke one or other little tasks; used to test lots of
bits of [[libpnd]] as it was developed.

===rawpxmltest===

Reads a given PXML.xml and spits out some of the fields found within.

===Test tools===

See the test/ dir in the libpnd source for assorted goofy little test apps used for testing bits of libpnd over time. They also may serve as source examples for using some of the APIs. They're old and shoddy probably too.

==How does it work?==

This is just a quick summary to save you guessing by reading [[PXML_specification|this whole document]].

In essence, libpnd includes lots of real code, but in many places it passes heavy lifting off to shellscripts. This is both handy because the scripts are easily modified without recompilation, and further extends our design goals of making the library bindable to any other language.

Remember, PXML.xml directories are just as executable/mountable as .pnd apps.

So while libpnd is mostly straight-C and so easily bound to python or perl or whatever, libpnd itself invokes many scripts. Those scripts can be directly used by other applications, including other shellscripts.. so libnd functionality can even have bindings in other scripts. This is very flexible and powerful, and handy during debugging or SSHing into the Pandora, etc.

The application lifecycle goes like this:

* device is turned on
* during init, pndnotifyd is brought up and inhales the config giles
* pndnotidyd will attempt to auto-discover what PXML.xml directory apps and .pnd-file apps are in the configured searchpaths
* pndnotifyd will set up filesystem watches on the directories in the notify searchpath; if any of those directories are touched, pndnotifyd will wake up and re-auto-discover .. possibly removing .desktop entries or creating new ones. (i.e.: you drop a new app into the app searchpath, or remove one, or mount an SD card, etc. This is how appications immediately show up or vanish from the window manager desktops.)
* a libpnd aware launcher can execute applications direct (using libpnd)
* a libpnd unaware launcher can execute applications via the .desktop standard system; pndnotidyd will emit .desktop files as needed.
* when libpnd or a .desktop file need to execute an application, they do it via pnd_run.sh (which may be leveraged by other applications, but they hould use libpnd if they can instead, for utmost compatiblity down the road.) pnd_run.sh does the mount of the ISO, runs the actual execable and so on, as directed by libpnd or the command-line args from the .desktop. pnd_run.sh will clean up after everything as well.

So it all works like magic, but it is not that complex a system once you've got the hang of what all is going on.

application → libpnd → shellscripts → system

==FAQ: IF you want to make files visible to the apps, do you have to modify the pnd?==

No. When apps write back to themselves, the writes go to their /pandora/appdata on the SD that houses them. The next time the app reads a file in its directory, the OS will ensure they get the newer file, which is the one in the appdata.

Likewise, you can just drop a file into the appdata and the app will see it.

The app doesn't know about appdata and its pnd file.. the OS and libpnd take care of all the magic.. the app sees one directory, but the reality is there is magic merging going on behind the scenes.

==Assumptions about the filesystem and Configuration==

Note that for libpnd to work, it makes certain assumptions about the filesystem and config files. Since libpnd was developed with the images it should work for the Pandora .. but just dropping libpnd onto another Linux distribution and it won't likely 'work out of the box'. Certain config files will need to be set, and certain conventions followed.

===Searchpaths===

libpnd was designed so that most everything is configured in files, and that these files should be easily hackable and easily overriden, without compromising the machine. It should be feasible to add a config file to an SD card, have it take over if available when required, and then 'undo' those configs simply by removal of the SD card and rebooting.

To facilitate this design goal, all config files are 'sought' using a search-path system.

Developers should be mindful of using the libpnd APIs so this behaviour is inherited to interested applications; developers could also reuse the logic for searching for files, if they find it useful.

Searchpaths are colon-delimited list of paths, searched left to right.

ex: foo:bar:/my/baz means to look for a given file in 'foo', then in 'bar', then in '/my/baz'.

The standard config files have a default searchpath, and those config files will define further searchpaths for scripts and such the system uses. This makes the system highly flexible -- default scripts are included, but can be overridden by dropping the right named script on an SD card, or by altering a config file.

See the example config files below for example searchpaths -- i.e.: how pndnotifyd searches for pnd_run, etc.

===Notification paths===

The 'apps' config includes a searchpath that specifies the sub-paths to be 'watched'. Various watch mechanisms exist for various filesystem types, but over the course of Pandora development (various kernels, various k-modules, various DM and WM's, I found the included system most stable, though not most current. After a final device image is settled on, it might be time to alter the notification system, but it should not impact the libpnd API.)

Anyway, watches are placed upon the paths defined, and if anything in those paths changes, the auto-discovery code is kicked off to seek our PXML.xml and .pnd type applications in the search paths.

Note that searchpath and notifypaths are different (and usually very similar, but have the option to be very different.)

===Config files===

libpnd includes a generic simple config file parser and assumes the presence of a few config files. It also includes defaults
so if a config is missing or broken things should work.

In general, Pandora specific config files should be located in:
<pre>
/etc/pandora/conf
</pre>

The config files are:
{|class="wikitable"
!!File!!Description
|-
|conf||this file is generally _not_ included with the Pandora and left to default; its job is to define the basic default searchpath for config files, so should you wish to override things entirely, you may need to alter this file. i.e.: If you wish to switch to test config files on SD or in /tmp, instead of using any other conf files .. you can create this guy. This provides a mechanism to short circuit the entire conf system.
|-
|apps||this config file defines auto-discovery and other application bundle parameters
|-
|desktop||this config defines "dotdesktop" .desktop and FreeDesktop integration paramters -- example is where to spit out icons or .desktop files from discovered PXML.xml or pnd applications
|-
|categories||this config maps PXML.xml spec based categories to FreeDesktop standard categories; in this way a PXML based applicatoin can show up in the appropriate categories of a WM that does not use libpnd
|}

====conf File====

No default is included with the distribution.

The default search path is reasonable and assumes we want the official /etc/pandora/conf near the end, with checks to the SD cards for overrides first. (Likely most people will not override, so the canonical location will be used 99.9% of the time.)

<pre>
#define PND_CONF_SEARCHPATH "/media/mmcblk0p1/pandora/conf:/media/mmcblk1p1/pandora/conf:/etc/pandora/conf:./testdata/conf"
</pre>

The key for override is:

<pre>
#define PND_CONF_KEY "conf.searchpath" /* if not found, use PND_CONF_SEARCHPATH */
</pre>

Which suggests using something like this.

<pre>
[conf]
searchpath /foo/bar:/baz/bing
</pre>

====desktop File====

<pre>
# Open Pandora
# Desktop configuration

[dotfiles]
#(~/Desktop for xfce, /usr/share/applications for WMs that actually follow spec)
dotdesktoppath ~/Desktop/ # path for pndnotifyd to spit .desktop files into (run as root)
iconpath /tmp # path for pndnotifyd to drop icons into (can be same as .desktop if WM permits)

[launcher]
# if hupscript is commented out entirely, pndnotifyd will not try to find/run the hup
# if it is uncommented, pndnotifyd will attempt to invoke the hupscript after emitting .desktop files
# (the hupscript exists to hup the WMs to redisplay .desktop apps)
#hupscript pnd_hup.sh
</pre>

====apps File====

<pre>
# Open Pandora
# Application configuration

[autodiscovery]
# searchpath is a list of paths (colon separated) in which to look for PXML.xml or .pnd-file applications
searchpath /media/*/pandora/apps:/usr/pandora/apps
# notifypath is a list of paths to monitor; if anything in those paths changes, the searchpath is rescanned
# note that for each path chunk, all current subdirs of that path are also watched)
notifypath /media:/media/*/pandora/apps:/usr/pandora/apps:./testdata/app?

# PXMLs may be overridden .. i.e.: overrides are a subset of PXML, where the values are copied over the full PXML
[overrides]
# searchpath to look for PXML overrides (which are named by the unique-id)
searchpath ~/pxml-overrides

# [pnd] defines where to locate the pnd support scripts, so the user may override pnd_run.sh without clobbering built in
[pnd]
searchpath /media/*/pandora/scripts:/usr/pandora/scripts
runscript pnd_run.sh
</pre>

====categories File====

<pre>
# Open Pandora
# dotdesktop configuration

# this config file maps 'PXML' categories to free-desktop standard categories
# i.e.: category 'Foo' could map to more standard 'Utility', thus making .desktop file
# emitting a more useful thing

# the standard listing of categories is:
# http://standards.freedesktop.org/menu-spec/latest/apa.html

# note that 'map' section in the config is _required_ for a match to be found; this
# is done to separate categories from (future) top-level directives

default Application;Utility;Network;

[map]
Development Development
Education Education
Games Game
Graphics Graphics
Internet Network
Multimedia AudioVideo
Office Office
Settings Settings
System System
Utilities Utility
</pre>

===SD card layout===

libpnd concerns itself with things in the 'pandora' root folder on SD. We agonized over this decision, but settled on this to avoid cases where someone with a 16GB SDHC card puts 50-million files with ".pnd" on them, and expects reasonable performance. Instead, applications for instance would have to be in:

<pre>
/pandora/menu -> apps that will go to /usr/share/applications and should show up in xfce menu by category
/pandora/desktop -> apps that will go to ~/Desktop and show up on user desktop as icons
</pre>

The following location is used by pmenu (and may get deprecated, but I've not discussed it with cpasjuste yet.)

<pre>
/pandora/apps
</pre>

i.e.: the searchpath for autodiscovery includes /media/*/pandora/apps (and desktop and menu now)

Also in the /pandora/ folder is a magic 'appdata' folder:

<pre>
/pandora/appdata
</pre>

When a .pndfile or PXML.xml dir get mounted, any writes back to the mounted area are put into appdata, with a subdir by the unique-id. i.e.: With the hypothetical MAME.pnd, it might update its config files after a user changes something, or create new files, or store hiscores or whatever. If it doesn't write them to [[NAND]], and doesn't want ot write them to /mame/some/dir, but instead record it to itself for whatever reason, it would go to /pandora/appdata/MAMEs-ID/ instead. The pnd or PXML.xml app area is never modified during a run, only the appdata. (But when an application reads its own path, it will pick up the appdata version of the file instead of the actual file. Then magic of union-type filesystems!)

Example:

If Myapp with unique-id foo.123 is mounted, then any write-backs are directed to..

/pandora/appdata/foo.123/

On the SD that hosts the application.

===NAND layout===

In addition to seeking applications in [[SD cards]], /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.

It might be a cool addition to put a user homedir into the searchpath as well, so [[NAND]] but user-homedir (for on-device browser downloads, say.)

==Command line tools and testing==

A number of scripts and tools are included or built with libpnd, to facilitate testing of the lib as its being developed and to assist in making .pnd files and PXML.xml files.

==PXML.xml and .pnd files==

On most platforms, applications are distributed as an executable and optional datafiles and likely an installer. The installers job is to integrate the application into the filesystem, as the transport mechanism itself is not executable and is considered temporary. In Windows an application might be installed into Program Files, while in Unix an application might be dropped into /usr/local/bin .. data files in various other places.

For the Pandora platform we wanted a very easy to use workflow -- download and run -- and also have a very different operating environment. With multiple SD cards available for expansion (and that space being highly desirable due to a smaller internal store) it is desirable to install applications to SD, and yet SD cards are by definition something users will wish to carry multiple of. With two slots, it could be quite a chore to install an application to SD1, its data to SD2, and then say have only one of them plugged in at a time, or switch which slot they're in, or any number of scenarios. i.e.: Installing onto a medium which may be present or not at any time is very different to how most operating systems work. So we made something new and awesome.

The PXML.xml and .pnd-file approach we came up with attempts to address these issues.

The goals:
* for the user, an application can be a single file download
* furthermore, there is no installation whatsoever, beyond dropping that single file into the right place on the SD card
* using the application should be easy -- stick in the SD card, and tap/launch on the icon.
* for uninstallation, delete the single file. Thats it, no fuss.
* for the developer, creating that single file should be easy to do
* for the system, performance should be high

Remember, an application can be a .pnd 'bundle' (single file containing all the sub-files), or a PXML.xml 'dir application' (an unpacked .pnd esentially.) '''BOTH PXML.xml-dirs and .pnd's ARE EXECUTABLE.'''

pndnotifyd will auto-discover PXML.xml in a directory and consider that an application, emitting a .desktop file, just as well as a .pnd file. i.e.: This can be hand for development or users. Remember that a mounted PXML.xml dir still redirect write-backs to the /pandora/appdata directory, just like a full .pnd application. They are treated the same!

===What are PXML.xml and .pnd files?===

PXML.xml is a file describing an application
A directory containing a PXML.xml _is executable_
A .pnd file is the packaged up version of the directory that is executable.
i.e.: a PXML.xml in a directory is just as executable as a .pnd representation of that directory.

Example:

<pre>
mkdir OutcaST
cp outcast.bin OutcaST/
cp PXML.xml OutcaST/
# at this point, the OutcaST directory is now discoverable and executable
</pre>

pnd_make.sh -this -that OutcaST outcast.pnd
# at this point, outcast.pnd is executable (as is the OutcaST directory), so upload outcast.pnd to the Open Handhelds Archive and let people enjoy!

===A note on including shared libs===
A philsophy for packaging that I am advocating is to 'just make applications work' -- avoid dependancy trees.

Some guidelines:

1) you can depend on shared libs included with the firmware to always be there

2 you should include any shared libs you need for your app, that are not in the firmware (yes, this increases app size a little bit, and potentially makes for duplication among apps that use the same shared libs)

3) if a shared lib becomes desirable in the firmware, it can be added there as a firmware patch easily (this has the advantage of gradulaly updating the entire user based, and apps easily saying 'we depend in firmware version X', rather than making for pnd-dependnacies and the equivilent of 'dll hell'

4) You'll have to be careful in linking your application to ensure that the shared libs you are including in the pnd/PXML-dir are to be locatable by your binaries. ie: stick them in a 'lib/' dir in your bundle, and stamp your binary with a library-path './dir/' so they can be found, say. More later.

===Future idea: pnd's for containing system-wide shared libs===

This is something we've bounced around for quite awhile, but not committed to. As it keeps coming up I thought I'd put some notes here in public.

It is possibly desirable to make a special searchpath that is discovered during machine boot, and any pnd's found there are automatically mounted (and left mounted) into a special path (say /usr/local/pandora/lib or somesuch.) This way, collections of handy utilities or shared libraries could be distributed as a pnd, and become available in consistent locations. If 10 applications need a shared lib, and don't want to duplciate it in each of their pnd files, this could be an approach.

I tend to think it is best avoided, however, since it complicates the user experience -- we end up with pnd depandancies, and apps nolonger about to 'just work', and apps that did work and 'suddenly break' when other files are altered. The philosphy we're going for with pnd files is 'drag and drop' -- user downloads a pnd file, and it works.. a self contained application, nice and easy. We start complicating the dependancies, and it turns into 'dll hell' as seen on other platforms.

That said, it is _not_ difficult to add into the existing system and design; we've been mulling it over, but it is best avoided for now. rather than complicate the system up front, let us try to get a functional and as lightweight-as-possible system on the uptake, gather some usage data points and then worry about upgrades :)

===File format - PXML.xml / PXML Specification===
See the [[PXML_specification|PXML specification]]

Alternatively the spec is included in the docs/ directory of the libpnd distribution, though the wiki version linked above should be considered cannon.

A note on history; the PXML spec was originally created by EvilDragon, and went through a number of revisions as suggestions came in; as these things are wont to do, the target was ever moving and the scope and meaning of PXML changed so at some point a more strategic approach was needed. dflemstr took it upon himself to help recode some of the parse and re-evaluate many of the PXML decisions and hence was born the PXML-version-2 spec.

===File format - .pnd files===
The pnd file format is pretty straight forward, though most will interact with it through the included (or community supplied) tools.

Basically its just an ISO file (or other filesystem type) with a PXML.xml and an optional PNG icon appended. (example: cat appfolder.iso app.pxml icon.png > app.pnd) For ease of discussion, I refer to ISO but in fact you coudl be using squashfs or other types.

The ISO filesystem portion of the file can include anything the developer wishes, as long as it includes a PXML.xml in its root file and an executable somewhere in there. It can also include images, audio files, data files of any kind. It can be small or large.

Yes, the PXML.xml is included in the ISO portion (in the root directory), and also appended to the end of the .pnd file (for _convenience_ .. it is very easy and fast to locate in this position; we can backseek into the ISO to find the PXML, but if its a 500MB ISO it could take awhile. Hence, we append it and can find it in one seek.)

'''NOTE: The naming of the PXML.xml file is important! The name is case sensitive and must be "PXML.xml", nothing else!'''

This simple format makes it possible to easily create .pnd files with the default utility's of most operating systems. Further, it is a fairly fail-safe system -- the PXML is appended, but is also included within the ISO image part of the file so if the appended-PXML is ever lost (unpack and repack poorly, say) the system will still work (the PXML inside the ISO can be found easily, even without mounting the ISO _as_ an ISO, since it is a plaintext uncompressed image format.)

Manually creating a .pnd (or even a PXML) is a pain so there will be a few helper scripts or maybe even a gui app out when we launch.

Included with libpnd are some scripts to create PXML and pndfiles, though it is expected people will create handier utilities. See the tool section of this wiki for some details.

Question from the gp32x forum regarding confusion of PXML location -- remember that in general most developers will keep a directory that represents the .pnd or PXML-dir application. Their makefile/build-process will drop the executable(s) into that directory, which inludes a PXML.xml description of the application, and possibly an icon (and whatever all else they wish.) To build the .pnd file, a script (say) is used which compresses all this into the pnd format (including appending the PXML.) So yes, the PXML is in two places in the .pnd file and one place in the source directory. You'll get used to it ;)

Rationale --

Several iterations of pnd files have been considered, from zipfiles to cramfs to other formats, to putting in a key/value set of information tags in the file, to table-of-contents indexes, to any number of options to help performance, and so on. In the end we went for a good overall and simple solution and dropped getting fancy -- PXML.xml can be extended to define the type of the file if it cannot be magic'd, so we could using other filesystem types in the future (and this is why people should use libpnd rather than rolling their own solution.) For now however, pnd files are ISO files with the PXML.xml appended and an optional icon. This keeps the PXML and icon easy to locate, and yet a easy file format.

====Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file====

These are guidelines to make pnd-files 'well behaved', and to help move towards a consistent pnd structure.

* Always include your icon png-file and PXML.xml file in the _Root_ of the pnd-file; this is for reasons that folks may well unpack the pnd-file, and then repack it; in doing so, if the icon and PXML.xml (normally appended to the .iso to become a .pnd) will be lost, unless the user or tool is being careful. Thus, it is wise to include them within the .iso, to make things so the iso is the entire pnd application, in unpacked form.

* Use a 'reasonably unique' unique-id of course (to identify your application.) This is used for many internal uses, so uniqueness is pretty wise.

* Use an 'application relevent' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.

* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)

* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.

* Try using rudimentary zenity scripts to pop up imporant pre-run information, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened

* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!

* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.

* For data that is not kept in your appdata directory, try to keep it local to the current SD _or_ better still, search both SD. ie: libpnd uses a basic but really handy system for iterating across a list of directories (including glob type expansion); so you can tell it something like /media/*/foo:/tmp and it'll check every mounted device (including both SD slots) in the 'foo' directory, as well as /tmp; you can have it call your code as it looks through, or you can ask libpnd to find a file for you and report where it was found, across all your searchpaths; you don't have to use libpnd's code to do it, you coudl write oyur own (using libpnd as an example if you need the help), as its pretty easy to build (20 lines of code maybe?) Anyway, the trick is to be multi-SD aware, and bonus marks for handling if theres a USB mounted drive etc as well. (Example; I coded minimenu so that when it caches out a preview picture, it checks for free space first, and tries first on the same SD that the pnd is mounting from, and then across a searchpath of alternate locations to cache to; this way the user can customize the caching, and it can be on various devices.)

====What filesystem types can be contained within a pnd-file?====

The pnd container can really contain a large variety of filesystem types; day-zero we're aiming for ISO since it is simple, easy build across every major OS, and fast to use. But it is not the only supported filesystem type, and more should be added all the time. (Possibly '-auto' can be added to pnd-run and it'll "just work" for dozens of types!)

A compressed filesystem type has always been desirable for file sizing reasons, though it potentially impacts performance (depending on the application operation really.)

Supported types (not an exhaustive list!):

* ISO
* squashfs

===Creating pnd files===

The [[PND quickstart]] page contains this information.

===PXML overrides===

There are a couple of ways to effect an override of the PXML, without modifying a pnd-file.

===="In-path" override files: .ovr====

The library automatically imports a limited number of overrides from a conf file that can be located in the same location as its matching .pnd file is.

For instance, if /pandora/desktop/awesomegame.pnd exists, then libpnd will automatically also search for /pandora/desktop/awesomegame.ovr

Some menu systems will also be smart enough to watch for an icon override -- /pandora/desktop/awesomegame.png -- and if present, to use it; 'minimenu' (mmenu) is aware of that, as is pndnotifyd daemon when emitting .desktop files. Likely pmenu will also be updated. In effect, the user can override the icon, category and other attributes of the pnd, without needing special tools or to alter the system.

An .ovr file must be named identically to the pnd-file, excepting the 3 character file extension.

NOTE: Given that a pnd may emit multiple applications from its PXML.xml, the ovr will have to be aware of this so it can override the correct application(s) within the pnd. Some menus and information tools will display the application list with 'subapp number' to assist identification. minimenu shows the subapp number in the detail panel, for example. In the case where a pnd-file has only one contained application, that is subapp-number zero. For any additional subapplications, increment by one .. but it can be tricky to know which app is which subapp number. (A careful eye will notice the .desktop filename includes the subapp-number after the pound sign .. foo#3.desktop is subapp_number 3.)

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 note text line 1
</source>

====PXML override file -- currently unsupported====

PXML.xml files can have any number of their elements over-ridden by user preferences.

The design goal here was to make it so user-preferences could alter the impact of the PXML.xml in any way, but without requiring the actual PXML.xml in the .pnd (and within the ISO therein) to be altered (could be a 500MB ISO after all!), and further, for these changes to persist. Consider than an SD card could be removed and inserted into the other slot, or the app could be removed entirely and come back another day, or other scenarios.

As such, the PXML-overrides are kept in NAND in the user homedirectory (See the config files to find out where.)

libpnd includes functions to pull in PXML, and also functions to then look for and merge in overrides. It is not always done since you may wish to inspect the PXML or the overrides, so the developers job is to do as they see fit -- pull the XML, and likely also pull in the overrides.

At this time I'm not sure if people will ever use overrides, but the system has been built in should it be needed.

===Included shellscripts to generate files and other sundry duties===

====genpxml====

This tool can spit out a basic but correct PXML.xml, faking up a halfway-useful unique-id in the process. It might be handy in saving you writing up a PXML.xml from scratch.

====pnd_hup.sh====

pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out whom to HUP.

====pnd_make.sh====

This is one of the great ones :)

Given a directory with a PXML.xml (see genpxml above) and an executable and any other goo you want in there, this script will spit out a .pnd file you can execute or distribute as an application.

====pnd_run.sh====

This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it dorectly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.

==Auto-discovery of applications==

TBD.

==Integration with FreeDesktop .desktop systems==

===dotdesktop (.desktop) files===

===Icons===

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.

==APIs==

Feel free to just go read the .h files; I have tried to comment liberally :)

===Setting and Getting the CPU clock speed===

===Device paramaters - brightness, etc===

===PND files, exec and mount===

===Application discovery===

===Config file parsing===

===Boxing, the singly-linked list container===

===Directory watching===

===Logging api===

[[Category:Development]]
[[Category:PND]]

Libpnd hub

2012-01-15T23:07:37Z

Porg: /* pnd_hup.sh */ Grammar: "whom" as this pronoun addresses an object!

:''Basic users will be more interested in the page [[Introduction to PNDs]]''

{{TOC limit|limit=3}}

{{split section|To much text, a lot of things could be outsourced to dedicated shorter articles}}

=Overview=

[[libpnd]] is a basic collection of functions and tools to make working Pandora-specific operations easier; to wit, it is hoped multiple applications will make use of this library rather than re-implement similar functionality and lead to problems down the road. (Instead we can run into problems together and thus clobberize them.)

[[libpnd]] thus is a collection of:

* handy system code that hopefully is reusable - IO functions, CPU clock setting, etc.
* applications for supporting the Pandora's unique features, such as ''pndnotifyd'' for auto-discovery of PXML and .pnd applicatons
* libraries for support of the .pnd and PXML systems; i.e.: for locating, executable, mounting and unmounting PXML-directory and .pnd applications, loading PXML and handling overrides
* hopefully reusable code for support of these things; i.e.: a rudimentary but useful config-file parser, rudimentary singly-linked-list container, etc.

It will also include utility functions for setting the CPU clock, reading GPIO inputs without depending on SDL, and other handy bits.

'''You can, nay, are required to - contribute to libpnd!'''

==Design considerations and philosophy==

While much of [[libpnd]] is obvious, some decisions had to be made and it may help to know the guiding principle behind it; the Pandora device will be a handheld '''computer''', but libpnd is designed to facilitate certain operations with goals towards..

* simplicity - just work right, configuration not generally needed
* obviousness - work as one would expect for this sort of device; i.e.: the user assumes something will work a certain way, and it does
* like other guys - as an extension of the prior point, we have tried to follow UNIX spirit and provide reusable small tools to do the work those bits can be leveraged, but further tried to follow the spirit of other consoles. So while the device is a powerful little computer, it is probably going to be used by gaming and retro enthusiasts and so we color some of our decisions that way. (i.e.: consider that a PS2/xbox/PSP/etc will have save-game or data management as a separate application, for instance. If thats the best multi-million dollar companies can come up with over decades, well, its not so bad for us to fall back on!)
* not over-defined; libpnd and PXML try to define a bunch of things, but we also do not _over define_; we try to lead by providing examples and styles, and while we have designed ahead for many things, we have also not nailed a lot of that down too early. It is better to be simple and shipped, then complex and a mess.. adaptable rather than scary.

The library is of course broken into parts:
{|class="wikitable"
!Part!!Comment
|-
|include||include these files to make use of the lib
|-
|lib||the code that produces the lib
|-
|test||mini tools to test various pieces of the lib in isolation
|-
|bin||test tools - tools for testing the lib as it is developed, not anticipated to be used by many
|-
|testdata/||for testing /etc/pandora; will contain 'conf' dir, for example
|-
|apps/||actual applications people may use, such as [[pndnotifyd]]
|-
|}

For now though, here are a couple notes about the design.
* it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it). I have gone out of my way to limit external references so that bindings are easier to make.
* contrary to the previous comment, we've used a bit of C++ for the tinyxml parser .. hopefully this is not an issue.
* I have tried to keep the API relatively simple and am faking some OO like data hiding to try to keep dev noses out of structures that are subject to change. i.e.: functions for list management and node access are provided, don't dig into the void* cast structs, or you could get burnt.
* the API should be pretty stable; so far very few user-code changes have ever been needed.. lib internal changes should be binary compatible.
* As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself
* As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)
* The lib works pretty well, but there is room for improvement internally; it won't hurt my feelings for you to suggest improvements, and I'm sure we would all be grateful for any patches you provide. We've _started_ this library, but by no means wish to carry it alone!

==Opportunities for improvement==

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

* Better ISO lang handling ... due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)
* Validation of files when they're loaded
* An actual parser of PXML metadata

[[New PND format | This page describes a proposed new PND format.]]

==License==

libpnd (including all the apps etc) are released under the LGPL (ie: so there should be no encumbrances that prevent linking to commercial applications.):

GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999

==Obtaining the library==

libpnd is in the Official Pandora GIT repo: [http://git.openpandora.org/cgi-bin/gitweb.cgi]
To obtain yourself a copy, use something like:
<pre>
git clone git://git.openpandora.org/pandora-libraries.git
</pre>
Thats all you normally need. For copy-paste from the private Wiki sake, heres what I had before:
Without going into how to set up a GIT, the summary that I (as a registered dev in the repo) used was:

<source lang="bash">
mkdir libpnd
cd libpnd
git init
git remote add libpnd ssh://foo@git.openpandora.org/srv/git/pandora-libraries.git
git push libpnd master
</source>

==Building the library==

Standard 'make' should be sufficient here; pull down the directory from the GIT, cd into it, and run make. Thats it.

Note that the make default target is 'everything', which will emit:
<source lang="bash">
libpnd.a - the static linked version of the lib
libpnd.so.1.0.1 - the dynlinked version
libpnd.so.1 - the stub for the shared lib; i.e.: apps should link against libpnd.so.1 and not the 1.0.1 over-specific version
bin/* - the 'test' dir and the 'apps' dir builds will end up in bin
</source>

There are a few additional make targets, however.

{|class="wikitable"
!Target!!Description
|-
|make clean||wipes out the object files, the bin files, and *~* (emacs backup files), empties some of the deploy stuff, etc. Do this before committing to GIT or we will beat you with sticks.
|-
|make deploy||populates the deploy/ directory, which is what is used inthe shipping images; i.e.: testdata/conf includes test configs, while deploy/etc/pandora/conf includes the configs we ship with. This
|-
|make||will copy over some of the libs and binaries and such.
|-
|make pnd||create a few sample pnd files for testing the lib on an x86 machine
|}

==Included Applications==

===pndnotifyd===

Manages the auto-discovery mechanism and integrating PXML.xml dir-apps and [[.pnd]] files into the FreeDesktop standard system (.desktop files). A dedicated libpnd-aware menu could leverage libpnd directly and not need [[pndnotifyd]], though pndnotifyd does offer some handy bits such as HUPping apps to suggest to them that applications may have been added/removed (libpnd includes all the necessary functions for this as well.)

===pndvalidator===

Is mostly a skeleton right now; in the future, it is hoped it will inspect a PXML.xml and then check to ensure the referenced assets are present; the goal to validate the PXML.xml is spec compliant, and the resulting application would be useful.

===discotest===

One of the test tools; it essentially runs an auto-discovery to list off the found apps (be they PXML.xml dir apps or .pnd files), and can dump various data or invoke one or other little tasks; used to test lots of
bits of [[libpnd]] as it was developed.

===rawpxmltest===

Reads a given PXML.xml and spits out some of the fields found within.

===Test tools===

See the test/ dir in the libpnd source for assorted goofy little test apps used for testing bits of libpnd over time. They also may serve as source examples for using some of the APIs. They're old and shoddy probably too.

==How does it work?==

This is just a quick summary to save you guessing by reading [[PXML_specification|this whole document]].

In essence, libpnd includes lots of real code, but in many places it passes heavy lifting off to shellscripts. This is both handy because the scripts are easily modified without recompilation, and further extends our design goals of making the library bindable to any other language.

Remember, PXML.xml directories are just as executable/mountable as .pnd apps.

So while libpnd is mostly straight-C and so easily bound to python or perl or whatever, libpnd itself invokes many scripts. Those scripts can be directly used by other applications, including other shellscripts.. so libnd functionality can even have bindings in other scripts. This is very flexible and powerful, and handy during debugging or SSHing into the Pandora, etc.

The application lifecycle goes like this:

* device is turned on
* during init, pndnotifyd is brought up and inhales the config giles
* pndnotidyd will attempt to auto-discover what PXML.xml directory apps and .pnd-file apps are in the configured searchpaths
* pndnotifyd will set up filesystem watches on the directories in the notify searchpath; if any of those directories are touched, pndnotifyd will wake up and re-auto-discover .. possibly removing .desktop entries or creating new ones. (i.e.: you drop a new app into the app searchpath, or remove one, or mount an SD card, etc. This is how appications immediately show up or vanish from the window manager desktops.)
* a libpnd aware launcher can execute applications direct (using libpnd)
* a libpnd unaware launcher can execute applications via the .desktop standard system; pndnotidyd will emit .desktop files as needed.
* when libpnd or a .desktop file need to execute an application, they do it via pnd_run.sh (which may be leveraged by other applications, but they hould use libpnd if they can instead, for utmost compatiblity down the road.) pnd_run.sh does the mount of the ISO, runs the actual execable and so on, as directed by libpnd or the command-line args from the .desktop. pnd_run.sh will clean up after everything as well.

So it all works like magic, but it is not that complex a system once you've got the hang of what all is going on.

application → libpnd → shellscripts → system

==FAQ: IF you want to make files visible to the apps, do you have to modify the pnd?==

No. When apps write back to themselves, the writes go to their /pandora/appdata on the SD that houses them. The next time the app reads a file in its directory, the OS will ensure they get the newer file, which is the one in the appdata.

Likewise, you can just drop a file into the appdata and the app will see it.

The app doesn't know about appdata and its pnd file.. the OS and libpnd take care of all the magic.. the app sees one directory, but the reality is there is magic merging going on behind the scenes.

==Assumptions about the filesystem and Configuration==

Note that for libpnd to work, it makes certain assumptions about the filesystem and config files. Since libpnd was developed with the images it should work for the Pandora .. but just dropping libpnd onto another Linux distribution and it won't likely 'work out of the box'. Certain config files will need to be set, and certain conventions followed.

===Searchpaths===

libpnd was designed so that most everything is configured in files, and that these files should be easily hackable and easily overriden, without compromising the machine. It should be feasible to add a config file to an SD card, have it take over if available when required, and then 'undo' those configs simply by removal of the SD card and rebooting.

To facilitate this design goal, all config files are 'sought' using a search-path system.

Developers should be mindful of using the libpnd APIs so this behaviour is inherited to interested applications; developers could also reuse the logic for searching for files, if they find it useful.

Searchpaths are colon-delimited list of paths, searched left to right.

ex: foo:bar:/my/baz means to look for a given file in 'foo', then in 'bar', then in '/my/baz'.

The standard config files have a default searchpath, and those config files will define further searchpaths for scripts and such the system uses. This makes the system highly flexible -- default scripts are included, but can be overridden by dropping the right named script on an SD card, or by altering a config file.

See the example config files below for example searchpaths -- i.e.: how pndnotifyd searches for pnd_run, etc.

===Notification paths===

The 'apps' config includes a searchpath that specifies the sub-paths to be 'watched'. Various watch mechanisms exist for various filesystem types, but over the course of Pandora development (various kernels, various k-modules, various DM and WM's, I found the included system most stable, though not most current. After a final device image is settled on, it might be time to alter the notification system, but it should not impact the libpnd API.)

Anyway, watches are placed upon the paths defined, and if anything in those paths changes, the auto-discovery code is kicked off to seek our PXML.xml and .pnd type applications in the search paths.

Note that searchpath and notifypaths are different (and usually very similar, but have the option to be very different.)

===Config files===

libpnd includes a generic simple config file parser and assumes the presence of a few config files. It also includes defaults
so if a config is missing or broken things should work.

In general, Pandora specific config files should be located in:
<pre>
/etc/pandora/conf
</pre>

The config files are:
{|class="wikitable"
!!File!!Description
|-
|conf||this file is generally _not_ included with the Pandora and left to default; its job is to define the basic default searchpath for config files, so should you wish to override things entirely, you may need to alter this file. i.e.: If you wish to switch to test config files on SD or in /tmp, instead of using any other conf files .. you can create this guy. This provides a mechanism to short circuit the entire conf system.
|-
|apps||this config file defines auto-discovery and other application bundle parameters
|-
|desktop||this config defines "dotdesktop" .desktop and FreeDesktop integration paramters -- example is where to spit out icons or .desktop files from discovered PXML.xml or pnd applications
|-
|categories||this config maps PXML.xml spec based categories to FreeDesktop standard categories; in this way a PXML based applicatoin can show up in the appropriate categories of a WM that does not use libpnd
|}

====conf File====

No default is included with the distribution.

The default search path is reasonable and assumes we want the official /etc/pandora/conf near the end, with checks to the SD cards for overrides first. (Likely most people will not override, so the canonical location will be used 99.9% of the time.)

<pre>
#define PND_CONF_SEARCHPATH "/media/mmcblk0p1/pandora/conf:/media/mmcblk1p1/pandora/conf:/etc/pandora/conf:./testdata/conf"
</pre>

The key for override is:

<pre>
#define PND_CONF_KEY "conf.searchpath" /* if not found, use PND_CONF_SEARCHPATH */
</pre>

Which suggests using something like this.

<pre>
[conf]
searchpath /foo/bar:/baz/bing
</pre>

====desktop File====

<pre>
# Open Pandora
# Desktop configuration

[dotfiles]
#(~/Desktop for xfce, /usr/share/applications for WMs that actually follow spec)
dotdesktoppath ~/Desktop/ # path for pndnotifyd to spit .desktop files into (run as root)
iconpath /tmp # path for pndnotifyd to drop icons into (can be same as .desktop if WM permits)

[launcher]
# if hupscript is commented out entirely, pndnotifyd will not try to find/run the hup
# if it is uncommented, pndnotifyd will attempt to invoke the hupscript after emitting .desktop files
# (the hupscript exists to hup the WMs to redisplay .desktop apps)
#hupscript pnd_hup.sh
</pre>

====apps File====

<pre>
# Open Pandora
# Application configuration

[autodiscovery]
# searchpath is a list of paths (colon separated) in which to look for PXML.xml or .pnd-file applications
searchpath /media/*/pandora/apps:/usr/pandora/apps
# notifypath is a list of paths to monitor; if anything in those paths changes, the searchpath is rescanned
# note that for each path chunk, all current subdirs of that path are also watched)
notifypath /media:/media/*/pandora/apps:/usr/pandora/apps:./testdata/app?

# PXMLs may be overridden .. i.e.: overrides are a subset of PXML, where the values are copied over the full PXML
[overrides]
# searchpath to look for PXML overrides (which are named by the unique-id)
searchpath ~/pxml-overrides

# [pnd] defines where to locate the pnd support scripts, so the user may override pnd_run.sh without clobbering built in
[pnd]
searchpath /media/*/pandora/scripts:/usr/pandora/scripts
runscript pnd_run.sh
</pre>

====categories File====

<pre>
# Open Pandora
# dotdesktop configuration

# this config file maps 'PXML' categories to free-desktop standard categories
# i.e.: category 'Foo' could map to more standard 'Utility', thus making .desktop file
# emitting a more useful thing

# the standard listing of categories is:
# http://standards.freedesktop.org/menu-spec/latest/apa.html

# note that 'map' section in the config is _required_ for a match to be found; this
# is done to separate categories from (future) top-level directives

default Application;Utility;Network;

[map]
Development Development
Education Education
Games Game
Graphics Graphics
Internet Network
Multimedia AudioVideo
Office Office
Settings Settings
System System
Utilities Utility
</pre>

===SD card layout===

libpnd concerns itself with things in the 'pandora' root folder on SD. We agonized over this decision, but settled on this to avoid cases where someone with a 16GB SDHC card puts 50-million files with ".pnd" on them, and expects reasonable performance. Instead, applications for instance would have to be in:

<pre>
/pandora/menu -> apps that will go to /usr/share/applications and should show up in xfce menu by category
/pandora/desktop -> apps that will go to ~/Desktop and show up on user desktop as icons
</pre>

The following location is used by pmenu (and may get deprecated, but I've not discussed it with cpasjuste yet.)

<pre>
/pandora/apps
</pre>

i.e.: the searchpath for autodiscovery includes /media/*/pandora/apps (and desktop and menu now)

Also in the /pandora/ folder is a magic 'appdata' folder:

<pre>
/pandora/appdata
</pre>

When a .pndfile or PXML.xml dir get mounted, any writes back to the mounted area are put into appdata, with a subdir by the unique-id. i.e.: With the hypothetical MAME.pnd, it might update its config files after a user changes something, or create new files, or store hiscores or whatever. If it doesn't write them to [[NAND]], and doesn't want ot write them to /mame/some/dir, but instead record it to itself for whatever reason, it would go to /pandora/appdata/MAMEs-ID/ instead. The pnd or PXML.xml app area is never modified during a run, only the appdata. (But when an application reads its own path, it will pick up the appdata version of the file instead of the actual file. Then magic of union-type filesystems!)

Example:

If Myapp with unique-id foo.123 is mounted, then any write-backs are directed to..

/pandora/appdata/foo.123/

On the SD that hosts the application.

===NAND layout===

In addition to seeking applications in [[SD cards]], /usr/pandora/apps is included in the default searchpath, so that 'built in' apps can be listed, or users can drop them there.

It might be a cool addition to put a user homedir into the searchpath as well, so [[NAND]] but user-homedir (for on-device browser downloads, say.)

==Command line tools and testing==

A number of scripts and tools are included or built with libpnd, to facilitate testing of the lib as its being developed and to assist in making .pnd files and PXML.xml files.

==PXML.xml and .pnd files==

On most platforms, applications are distributed as an executable and optional datafiles and likely an installer. The installers job is to integrate the application into the filesystem, as the transport mechanism itself is not executable and is considered temporary. In Windows an application might be installed into Program Files, while in Unix an application might be dropped into /usr/local/bin .. data files in various other places.

For the Pandora platform we wanted a very easy to use workflow -- download and run -- and also have a very different operating environment. With multiple SD cards available for expansion (and that space being highly desirable due to a smaller internal store) it is desirable to install applications to SD, and yet SD cards are by definition something users will wish to carry multiple of. With two slots, it could be quite a chore to install an application to SD1, its data to SD2, and then say have only one of them plugged in at a time, or switch which slot they're in, or any number of scenarios. i.e.: Installing onto a medium which may be present or not at any time is very different to how most operating systems work. So we made something new and awesome.

The PXML.xml and .pnd-file approach we came up with attempts to address these issues.

The goals:
* for the user, an application can be a single file download
* furthermore, there is no installation whatsoever, beyond dropping that single file into the right place on the SD card
* using the application should be easy -- stick in the SD card, and tap/launch on the icon.
* for uninstallation, delete the single file. Thats it, no fuss.
* for the developer, creating that single file should be easy to do
* for the system, performance should be high

Remember, an application can be a .pnd 'bundle' (single file containing all the sub-files), or a PXML.xml 'dir application' (an unpacked .pnd esentially.) '''BOTH PXML.xml-dirs and .pnd's ARE EXECUTABLE.'''

pndnotifyd will auto-discover PXML.xml in a directory and consider that an application, emitting a .desktop file, just as well as a .pnd file. i.e.: This can be hand for development or users. Remember that a mounted PXML.xml dir still redirect write-backs to the /pandora/appdata directory, just like a full .pnd application. They are treated the same!

===What are PXML.xml and .pnd files?===

PXML.xml is a file describing an application
A directory containing a PXML.xml _is executable_
A .pnd file is the packaged up version of the directory that is executable.
i.e.: a PXML.xml in a directory is just as executable as a .pnd representation of that directory.

Example:

<pre>
mkdir OutcaST
cp outcast.bin OutcaST/
cp PXML.xml OutcaST/
# at this point, the OutcaST directory is now discoverable and executable
</pre>

pnd_make.sh -this -that OutcaST outcast.pnd
# at this point, outcast.pnd is executable (as is the OutcaST directory), so upload outcast.pnd to the Open Handhelds Archive and let people enjoy!

===A note on including shared libs===
A philsophy for packaging that I am advocating is to 'just make applications work' -- avoid dependancy trees.

Some guidelines:

1) you can depend on shared libs included with the firmware to always be there

2 you should include any shared libs you need for your app, that are not in the firmware (yes, this increases app size a little bit, and potentially makes for duplication among apps that use the same shared libs)

3) if a shared lib becomes desirable in the firmware, it can be added there as a firmware patch easily (this has the advantage of gradulaly updating the entire user based, and apps easily saying 'we depend in firmware version X', rather than making for pnd-dependnacies and the equivilent of 'dll hell'

4) You'll have to be careful in linking your application to ensure that the shared libs you are including in the pnd/PXML-dir are to be locatable by your binaries. ie: stick them in a 'lib/' dir in your bundle, and stamp your binary with a library-path './dir/' so they can be found, say. More later.

===Future idea: pnd's for containing system-wide shared libs===

This is something we've bounced around for quite awhile, but not committed to. As it keeps coming up I thought I'd put some notes here in public.

It is possibly desirable to make a special searchpath that is discovered during machine boot, and any pnd's found there are automatically mounted (and left mounted) into a special path (say /usr/local/pandora/lib or somesuch.) This way, collections of handy utilities or shared libraries could be distributed as a pnd, and become available in consistent locations. If 10 applications need a shared lib, and don't want to duplciate it in each of their pnd files, this could be an approach.

I tend to think it is best avoided, however, since it complicates the user experience -- we end up with pnd depandancies, and apps nolonger about to 'just work', and apps that did work and 'suddenly break' when other files are altered. The philosphy we're going for with pnd files is 'drag and drop' -- user downloads a pnd file, and it works.. a self contained application, nice and easy. We start complicating the dependancies, and it turns into 'dll hell' as seen on other platforms.

That said, it is _not_ difficult to add into the existing system and design; we've been mulling it over, but it is best avoided for now. rather than complicate the system up front, let us try to get a functional and as lightweight-as-possible system on the uptake, gather some usage data points and then worry about upgrades :)

===File format - PXML.xml / PXML Specification===
See the [[PXML_specification|PXML specification]]

Alternatively the spec is included in the docs/ directory of the libpnd distribution, though the wiki version linked above should be considered cannon.

A note on history; the PXML spec was originally created by EvilDragon, and went through a number of revisions as suggestions came in; as these things are wont to do, the target was ever moving and the scope and meaning of PXML changed so at some point a more strategic approach was needed. dflemstr took it upon himself to help recode some of the parse and re-evaluate many of the PXML decisions and hence was born the PXML-version-2 spec.

===File format - .pnd files===
The pnd file format is pretty straight forward, though most will interact with it through the included (or community supplied) tools.

Basically its just an ISO file (or other filesystem type) with a PXML.xml and an optional PNG icon appended. (example: cat appfolder.iso app.pxml icon.png > app.pnd) For ease of discussion, I refer to ISO but in fact you coudl be using squashfs or other types.

The ISO filesystem portion of the file can include anything the developer wishes, as long as it includes a PXML.xml in its root file and an executable somewhere in there. It can also include images, audio files, data files of any kind. It can be small or large.

Yes, the PXML.xml is included in the ISO portion (in the root directory), and also appended to the end of the .pnd file (for _convenience_ .. it is very easy and fast to locate in this position; we can backseek into the ISO to find the PXML, but if its a 500MB ISO it could take awhile. Hence, we append it and can find it in one seek.)

'''NOTE: The naming of the PXML.xml file is important! The name is case sensitive and must be "PXML.xml", nothing else!'''

This simple format makes it possible to easily create .pnd files with the default utility's of most operating systems. Further, it is a fairly fail-safe system -- the PXML is appended, but is also included within the ISO image part of the file so if the appended-PXML is ever lost (unpack and repack poorly, say) the system will still work (the PXML inside the ISO can be found easily, even without mounting the ISO _as_ an ISO, since it is a plaintext uncompressed image format.)

Manually creating a .pnd (or even a PXML) is a pain so there will be a few helper scripts or maybe even a gui app out when we launch.

Included with libpnd are some scripts to create PXML and pndfiles, though it is expected people will create handier utilities. See the tool section of this wiki for some details.

Question from the gp32x forum regarding confusion of PXML location -- remember that in general most developers will keep a directory that represents the .pnd or PXML-dir application. Their makefile/build-process will drop the executable(s) into that directory, which inludes a PXML.xml description of the application, and possibly an icon (and whatever all else they wish.) To build the .pnd file, a script (say) is used which compresses all this into the pnd format (including appending the PXML.) So yes, the PXML is in two places in the .pnd file and one place in the source directory. You'll get used to it ;)

Rationale --

Several iterations of pnd files have been considered, from zipfiles to cramfs to other formats, to putting in a key/value set of information tags in the file, to table-of-contents indexes, to any number of options to help performance, and so on. In the end we went for a good overall and simple solution and dropped getting fancy -- PXML.xml can be extended to define the type of the file if it cannot be magic'd, so we could using other filesystem types in the future (and this is why people should use libpnd rather than rolling their own solution.) For now however, pnd files are ISO files with the PXML.xml appended and an optional icon. This keeps the PXML and icon easy to locate, and yet a easy file format.

====Recommended layout of a pnd directory structure, ie: how to make a well behaved pnd file====

These are guidelines to make pnd-files 'well behaved', and to help move towards a consistent pnd structure.

* Always include your icon png-file and PXML.xml file in the _Root_ of the pnd-file; this is for reasons that folks may well unpack the pnd-file, and then repack it; in doing so, if the icon and PXML.xml (normally appended to the .iso to become a .pnd) will be lost, unless the user or tool is being careful. Thus, it is wise to include them within the .iso, to make things so the iso is the entire pnd application, in unpacked form.

* Use a 'reasonably unique' unique-id of course (to identify your application.) This is used for many internal uses, so uniqueness is pretty wise.

* Use an 'application relevent' appdata name; make it as unique as you have to, but consider being less unique; a random example could be .. possibly there may be several quake1 ports; they could all share the same appdata (same config files, same data files), but if you intend on having different config or data files than other quake1's, make your appdata named differently.

* Always include a documentation 'info' link, if your app has any setup requirements, has popup help screens that the user needs to know a key to pop up, or other essential trivia; feel free to make the doc link as complete as you like, since its all within the pnd file. (ie: Include the full DosBox documentation if you want to, in your DosBox pnd :)

* Try to set up the appdata directory for the user; if you need a 'roms' or 'image' directory in the appdata (such as in the case of an Atari ST emulator needing a location to house the TOS OS image, say), then do a 'mkdir' in your 'runscript', to create it. Thus the user will find a (example) Hatari appdata directory, and within, any directories he needs (possibly empty.) This just makes it obvious for the user where to put stuff.

* Try using rudimentary zenity scripts to pop up imporant pre-run information, if the application can't do so; ie: Hatari itself has a very fine GUI in it, but if the Atari ST TOS image is not present, it just exits and fails to run, so the GUI doesn't have time to do anything useful. In this case, it could be wise to use a 1 line zenity script that checks before the emu runs for the file in question, then pop up a dialog box saying 'put this file /here', so the user knows what the heck happened

* Always Always Always write your 'state info' to current-working-directory (ie: ./foo, and not ~/foo). The pnd-system will redirect this to the users appdata of course, keeping things clean and predictable. If you're just porting an app, that has ~ all over the darned place, and you don't want to muck up the code.. just have your 'runscript' do something like 'set $HOME=.' and you're good to go!

* Runscripts; the PXML.xml can specify to run your binary, or you can run a .sh script that in turn runs your binary, say. This lets you do various tests, set up LD_LIBRARY_PATH, or other mischief before your binary gets run. Very handy. I often have PXML.xml run 'runfoo.sh', and runfoo.sh in turn runs ./foo after setting things up, making directories, etc.

* For data that is not kept in your appdata directory, try to keep it local to the current SD _or_ better still, search both SD. ie: libpnd uses a basic but really handy system for iterating across a list of directories (including glob type expansion); so you can tell it something like /media/*/foo:/tmp and it'll check every mounted device (including both SD slots) in the 'foo' directory, as well as /tmp; you can have it call your code as it looks through, or you can ask libpnd to find a file for you and report where it was found, across all your searchpaths; you don't have to use libpnd's code to do it, you coudl write oyur own (using libpnd as an example if you need the help), as its pretty easy to build (20 lines of code maybe?) Anyway, the trick is to be multi-SD aware, and bonus marks for handling if theres a USB mounted drive etc as well. (Example; I coded minimenu so that when it caches out a preview picture, it checks for free space first, and tries first on the same SD that the pnd is mounting from, and then across a searchpath of alternate locations to cache to; this way the user can customize the caching, and it can be on various devices.)

====What filesystem types can be contained within a pnd-file?====

The pnd container can really contain a large variety of filesystem types; day-zero we're aiming for ISO since it is simple, easy build across every major OS, and fast to use. But it is not the only supported filesystem type, and more should be added all the time. (Possibly '-auto' can be added to pnd-run and it'll "just work" for dozens of types!)

A compressed filesystem type has always been desirable for file sizing reasons, though it potentially impacts performance (depending on the application operation really.)

Supported types (not an exhaustive list!):

* ISO
* squashfs

====Creating pnd files===

The [[PND quickstart]] page contains this information.

===PXML overrides===

There are a couple of ways to effect an override of the PXML, without modifying a pnd-file.

===="In-path" override files: .ovr====

The library automatically imports a limited number of overrides from a conf file that can be located in the same location as its matching .pnd file is.

For instance, if /pandora/desktop/awesomegame.pnd exists, then libpnd will automatically also search for /pandora/desktop/awesomegame.ovr

Some menu systems will also be smart enough to watch for an icon override -- /pandora/desktop/awesomegame.png -- and if present, to use it; 'minimenu' (mmenu) is aware of that, as is pndnotifyd daemon when emitting .desktop files. Likely pmenu will also be updated. In effect, the user can override the icon, category and other attributes of the pnd, without needing special tools or to alter the system.

An .ovr file must be named identically to the pnd-file, excepting the 3 character file extension.

NOTE: Given that a pnd may emit multiple applications from its PXML.xml, the ovr will have to be aware of this so it can override the correct application(s) within the pnd. Some menus and information tools will display the application list with 'subapp number' to assist identification. minimenu shows the subapp number in the detail panel, for example. In the case where a pnd-file has only one contained application, that is subapp-number zero. For any additional subapplications, increment by one .. but it can be tricky to know which app is which subapp number. (A careful eye will notice the .desktop filename includes the subapp-number after the pound sign .. foo#3.desktop is subapp_number 3.)

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 note text line 1
</source>

====PXML override file -- currently unsupported====

PXML.xml files can have any number of their elements over-ridden by user preferences.

The design goal here was to make it so user-preferences could alter the impact of the PXML.xml in any way, but without requiring the actual PXML.xml in the .pnd (and within the ISO therein) to be altered (could be a 500MB ISO after all!), and further, for these changes to persist. Consider than an SD card could be removed and inserted into the other slot, or the app could be removed entirely and come back another day, or other scenarios.

As such, the PXML-overrides are kept in NAND in the user homedirectory (See the config files to find out where.)

libpnd includes functions to pull in PXML, and also functions to then look for and merge in overrides. It is not always done since you may wish to inspect the PXML or the overrides, so the developers job is to do as they see fit -- pull the XML, and likely also pull in the overrides.

At this time I'm not sure if people will ever use overrides, but the system has been built in should it be needed.

===Included shellscripts to generate files and other sundry duties===

====genpxml====

This tool can spit out a basic but correct PXML.xml, faking up a halfway-useful unique-id in the process. It might be handy in saving you writing up a PXML.xml from scratch.

====pnd_hup.sh====

pndnotifyd will attempt to locate this script and invoke it after an auto-discovery run, if the pnd_hup entry is present (and uncommented) in the config files. It is expected to be commented out in release images, as xfce watches directories for .desktop files and does not need a HUP; some desktop managers need to be HUPped to rescan for .desktop files in a timely fashion, so the pnd_hup config entry can be uncommented and this script will attempt to figure out whom to HUP.

====pnd_make.sh====

This is one of the great ones :)

Given a directory with a PXML.xml (see genpxml above) and an executable and any other goo you want in there, this script will spit out a .pnd file you can execute or distribute as an application.

====pnd_run.sh====

This job does a lot of the heavy lifting for libpnd, including setting up the 'union filesystems', doing .pnd and PXML.xml-app-dir execution and mounting, and so on. Generally you will talk to it via libpnd or .desktop files, but you can invoke it dorectly from your apps if you wish to circumvent libpnd or mount .pnd files within a shellscript/perlscript/etc.

==Auto-discovery of applications==

TBD.

==Integration with FreeDesktop .desktop systems==

===dotdesktop (.desktop) files===

===Icons===

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.

==APIs==

Feel free to just go read the .h files; I have tried to comment liberally :)

===Setting and Getting the CPU clock speed===

===Device paramaters - brightness, etc===

===PND files, exec and mount===

===Application discovery===

===Config file parsing===

===Boxing, the singly-linked list container===

===Directory watching===

===Logging api===

[[Category:Development]]
[[Category:PND]]

PCSX-ReARMed

2011-11-19T18:39:02Z

Porg: /* ROM Images */

{{warning|The information here is for version '''r8.''' Things may change in later versions as the emulator is updated.}}

{{Infobox Emulator|title=PCSX-ReARMed
|image=[[Image:Playstation-console.png|center|Playstation console]]
|download=[http://notaz.gp2x.de/releases/pcsxr/pcsx_rearmed_r8.pnd version r8]
|developer=[[Notaz]]
|porter=
|webpage=
|version=R8 (2011-03-21)
|status=Public Beta
|compatibility=[https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List (Google docs)]
}}
PCSX-ReARMed is a PlayStation 1 Emulator. A better alternative to [[PSX4Pandora]].

==Emulator Information==
===Development Status ===
In development with a beta version available.

===Compatibility===
A compatibility list is maintained as Google spreadsheet doc: [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 PSX compatibility list]

=== Related Links ===
*[http://www.gp32x.com/board/index.php?/topic/57973-pcsx-rearmed/ Development Thread & Discussion (GP32X)]
*[http://notaz.gp2x.de/cgi-bin/gitweb.cgi?p=pcsx_rearmed.git Source code (GIT)]

==Installation Instructions==
===Installation===
Download the latest version of the emulator from the repo ([http://repo.openpandora.org/?page=detail&app=package.pcsx_rearmed.notaz.r8 here]) and place it in one of the folders on your SD card according to the [[Introduction_to_PNDs#Where_do_.PNDs_Go.3F |PND guide]] (This guide will assume that you put the PND in /pandora/menu). In XFCE, the icon to the emulator should appear in the menu under 'menu -> Emulators -> PCSX-ReARMed' (if you put the PND in /pandora/menu), or on the desktop (if you put the PND in /pandora/desktop or /pandora/apps).

===ROM Images===
ROM files (Disc images) come in a range of formats, most commonly .iso, .img, .bin/.cue or .mdf/.mds. This emulator cannot handle compressed ROM files.
 
While it does not matter where the ROM files are placed, it is often easiest to put them somewhere that makes sense in relation to the PND for easy browsing. A good place to put them would be either in a clearly-named folder in the root of the SD card (e.g. /PS1) or in the same folder as the emulator PND (e.g. /pandora/menu/PS1). It does not matter how many ROM files are in the folder, or what directory structure is used.

Some images come as a .ecm file. These will not work in this emuator, but can be 'un-ECMed' by using the utility software [http://www.neillcorlett.com/ecm/ unecm], available at the linked website both as source code and as executable program files (=precompiled binaries, both 32 and 64 bit) for Windows, DOS, Mac OS X; on various Unix systems available through package managers as the package named "ecm"; and meanwhile also as a [http://notaz.gp2x.de/misc/pnd/unecm PND application by notaz].

=== BIOS ===
PCSX-ReARMed supports loading BIOSes. A minimum of one BIOS should be copied to [sd card]/pandora/appdata/pcsx_rearmed/bios/ ..and then selected in options->bios/plugins menu.
Loading a BIOS can potentially fix tons of bugs. It is highly recommended to activate it. A BIOS file is not strictly necessary, but not all games will work correctly without one.

==Usage==
[[Overclocking]] is often necessary to achieve acceptable emulation. See the [https://spreadsheets.google.com/ccc?key=0ArSWWAWRjErldHZVZlFxY0tBVnRRNXM5U3ZqWFNuN0E&hl=en#gid=0 Compatibility List] for each game's tested speed.

===Nub Control===
Nub control is disabled by default (left joystick is mapped to the D-Pad). To enable it, select 'Controls->Nubs as Buttons' in the menu.

===Loading a Game===
Upon staring the emulator, you will be presented with a GUI. Select (with B) 'Load CD Image', then navigate to the folder where you keep your image files. If you cannot find them, try selecting '/..' until the directory at the top of the list (in white) shows '/', then select '/media' then '/SD_CARD' where SD_CARD is the name of your card, then navigate to the folder where you placed the files. '''NOTE: Only select files highlightes as either blue or white. Grey files will not work.'''
 
At any time during gameplay, you can press the spacebar to return to the menu, pausing the game session. You can select 'Resume Game' to continue playing.

===Default Controls===
{|class="wikitable sortable" border="1" cellpadding="1" cellspacing="0" style="font-size: 90%; border:1px solid gray; border-collapse: collapse; text-align: center; width: 35%;"
|- style="background: #ececec"
! PS1 Controller Button
! Pandora Button
|-
|Triangle (Green)
|Y (Gamepad)
|-
|Circle (Red)
|B (Gamepad)
|-
|Square (Pink)
|A (Gamepad)
|-
|X (Blue)
|X (Gamepad)
|-
|Start
|Start
|-
|Select
|Select
|-
|R
|Right Shoulder
|-
|L
|Left Shoulder
|-
|D-Pad (Up, Down, Left, Right)
|D-Pad (Up, Down, Left, Right)
|-
|Left Analog Stick (Up, Down, Left, Right)
|Left Nub (Up, Down, Left, Right)
|-
|Right Analog Stick (Up, Down, Left, Right)
|Right nub (Up, Down, Left, Right)
|}

== Creating images of Games ==
A short how-to for doing this on Linux is available: [[Creating images of PSX games using Linux]]. On Windows you can probably rely on the common tools for creating disc images, like for example Alcohol or the likes. There were some reports in the forums that using Nero for creating images does not work.

[[Category:Emulators]]

Multisite username check

2011-11-10T18:26:59Z

Porg:

This is a suggestion by [[User:Porg|Porg]]. Participation is welcome!

In the user registration process at the various Open Pandora related sites (board, wiki, repo, bugtracker, …) [[User:Porg|Porg]] suggests to display the following hint:
----
'''Before registering your username''' here, you can run the [http://usernames.openpandora.org/check Pandora sphere username checker], which tests whether the username already exists within any other OpenPandora [http://usernames.openpandora.org/sites related sites]:
* '''As a courtesy to other users''', in order to not take their name away on other sites.
* '''For your own convenience''', to achieve a uniform nickname on all the OpenPandora sites, as a new arriving community member.
----

== ToDo ==

# Which Open Pandora relates websites (with user registration) are there? '''Anyone''' please add the URLs to the list below.
# Which site operators are willing to cooperate? '''Site operators''', please confirm your readiness, by writing your name plus short note next to the URL. Requirements for participating site operators:
## Offer a software interface (API) for testing whether a username exists at your site.
## Display the hint and link to or embed the checking service (iframe) into the registration page/process of your site.
# We need a web developer to create that multisite username checking service. '''Developer volunteers''', please participate in the [http://boards.openpandora.org/index.php?/topic/6068-suggestion-open-pandora-scene-multisite-username-checker/ discussion process], or enlist your dedication right below.

== Sites ==

URL of a Open Pandora related website which uses user registrations/logins + site operator(s) (nick)name and confirmation of participation + optional remarks:

http://boards.openpandora.org/

http://repo.openpandora.org/

http://apps.openpandora.org/

http://pandorawiki.org/

== Developers ==

Developers, who are willing to realize the multisite username checking service, please enlist your (nick)name and confirmation of participation plus optional remarks here: