Pandora Wiki - User contributions [en]

USB compatibility list

2011-04-15T18:38:47Z

Thomasjfox: /* External Game Controllers */

==Devices==

===Networking===
----

====HSDPA (3G) Modems====
{|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 in Linux
! Tested on Pandora
! Additional comments
|-
| Huawei E160
| Not required
| standard-A
| USB 2.0
| 250mA
| standard-A port
| Yes
| Yes
|
|-
| Huawei E160E
| Not required
| standard-A
| USB 2.0
| 250mA
| standard-A port
| Yes
| Yes
|
|-
| Huawei E220
| Not required
| standard-A
| USB 1.1
| 250mA
| standard-A port via High Speed hub
| Yes
| Yes*
| *The successful E220 tests were done by DJWillis on an old kernel (long before Pandora shipped). It seems that they are NOT working any more.
|-
| 4G-Systems XS Stick P14
| Not required (usbserial module)
| standard-A
| USB 2.0
| unknown
| standard-A port
| Yes
| Yes
| Requires usbmodeswitch program.
|-
| iPhone 3GS (Probably also 1G/3G)
| ipheth
| standard-A
| USB 2.0
| 500mA
| USB A
| Yes, works.
| Yes, works.
| 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
| USB A
| Yes, works.
| Yes, works.
| 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
! Driver
! Connector
! Supported standard
! Current draw
! Suggested connection to Pandora
! Tested in Linux
! Tested on Pandora
! Additional comments
|-
| Apple USB Ethernet Adapter MB442Z/A
| Not required
| standard-A
| USB 2.0
|
| standard-A port
| Yes
| Yes
| Works perfectly on the Pandora. Reportedly uses an ASIX AX88xxx chipset.
|-
| 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])
| Not required
| standard-A
| USB 2.0
| 250mA
| standard-A port
| Yes
| Yes
| ID 0b95:7720 ASIX Electronics Corp. AX88772 . Works perfectly on the Pandora. This clone from [http://www.dealextreme.com/details.dx/sku.5926 DealExtreme] works too.
|-
| Connectland USB 2.0 10/100M Ethernet Adapter
| Not required
| standard-A
| USB 2.0
| 250mA
| standard-A port
| Yes
| Yes
| ID 0b95:7720 ASIX Electronics Corp. AX88772 - Works fine, Sometimes a reboot is necessary (ZaxxonHF5RC1).
|-
| Belkin Gigabit USB 2.0 Network Adapter
| Not required
| standard-A
| USB 2.0
|
| standard-A port
| Yes
| Yes
| Works fine, 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 optermised), has horribly bright blue led's.
|-
| MosChip MCS7830 USB 10/100 Ethernet adapter
| Not required
| standard-A
| USB 2.0
|
| standard-A port
| Yes
| 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
| Not required
| standard-A
| USB 2.0
|
| standard-A port
| Yes
| Yes
| Works on Pandora (plug and play) - USB ID: 9710:7830 - bought from [http://www.dealextreme.com/details.dx/sku.22684 DealExtreme]
|-
| Digitus DN-10050 Fast Ethernet USB Adapter
| Not required
| standard-A
| USB 2.0
|
| standard-A port
| Yes
| Yes
| Another MosChip MCS7830 based adapter. USB ID 9710:7830.
|}

====USB WiFi adapters====
The Pandora stock kernel doesn't seem to come with any wireless driver support outside of the internal wifi chip. 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].

{|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 in Linux
! Tested on Pandora
! Additional comments
|-
| Belkin N1 Wireless USB Adapter (F5D8051) ("Ver. 2053") (MARVELL v1021)
| N/A
| Standard-A
| USB 2.0
|
| Not connecting it at all.
| Reported to work with ndiswrapper.
| 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.
|-
| Cisco/Linksys AE1000 High Performance Wireless-N USB Adapter
| rt3572sta (RT3572USB)
| Standard-A
| USB 2.0
|
| USB A
| Reportedly works.
| 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.'
|}

See also this thread [[http://www.gp32x.com/board/index.php?/topic/55570-new-pandora thread]] on the forums for the latest.

===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
! Additional comments
|-
| 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
| {{no|Not working on Pandora}}
| This drive does not work on a Pandora. 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. I have not yet tested this with a powered hub.
|-
| Verbatim 250GB Model #47580 Hard Drive
| Not required
| direct
| USB 2.0
| Unknown
| direct
| {{yes|Works on Pandora}}
| 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]. "worked an absolute treat when plugged into the Pandora. 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|Works on Pandora}}
| This drive works just fine with the Pandora.
|-
| 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|Works on Pandora}}
| Works perfectly fine with Pandora.
|-
| Western Digital 250GB My Passport Essential USB 2.0 2.5" Hard Drive
| Not required
| direct?
| USB 2.0
| Unknown
| direct?
| {{Partial|Maybe}}
| 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__877386 TheDarkSpectrum48K]. "Works perfectly!", but the 2nd 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__882635 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|Works on Pandora}}
| Tested by [http://www.gp32x.com/board/index.php?/user/14534-peca/ Peca]. "Works perfectly!"
|-
| 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|Works on Pandora}}
| Tested by [http://http://www.gp32x.com/board/index.php?/user/19191-mycohl/ Mycohl] This drive works without problems. Externally powered hub recommended to conserve battery power.
|-
| Seagate Seagate® Expansion™ External Drives
| Not required
| standard-A
| USB 2.0
| Unknown
| Direct
| {{no|Not working on Pandora}}
| 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)"
|-
| Freecom 250GB 2.5" portable
| Not Required
| standard-A
| USB 2.0
| Unknown
| Direct
| {{yes|Works on Pandora}}
| Just works perfectly when plugged into the Pandora. Inside it's a Samsung Model HM251JX so I guess anything based on that will also work OK.
|-
| Western Digital Elements 2TB 3.5" Hard Drive Model:WDBAAU0020HBK
| Not Required
| standard-A
| USB 2.0
| Unknown
| Direct
| {{yes|Works on Pandora}}
| Tested by [http://boards.openpandora.org/index.php?/user/430-kilowatt/ kilowatt]. No problems, works fine with Pandora.
|}

====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
! Tested in Linux
! Tested 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
| Yes
| No
|
|}

===Video display device===
----

====VGA DVI HDMI adapter====
{|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
! Tested in Linux
! Tested on Pandora
! Additional comments
|-
|
|
|
|
|
|
|
|
| No device tested yet
|}
====External graphic card====
{|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
! Tested in Linux
! Tested on Pandora
! Additional comments
|-
| Tritton see2 usb 2.0 to SVGA adapter
| sisusb
| USB
| USB 2.0
| reduces Pandora's battery life in half (10h → 4h)
| VGA (D-SUB)
| Yes
| Yes
| needs to be integrated with preferences, currently I must edit xorg.conf and mess with xinerama. Isn't too fast either, dragging a window is bearable, but forget about hi-res video. Good for presentations.
|}

===Video capture device===
----

====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
! Tested in Linux
! Tested 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
| Yes
| No
| Bought from [http://www.dealextreme.com/details.dx/sku.14991 DealExtreme]
|-
| Logitech Quickcam Communicate Deluxe
| Not required
| standard-A
| USB 2.0
| Unknown
| standard-A port
| Yes
| No
| USB ID: 046d:0992, works though [http://linux-uvc.berlios.de/ uvcvideo]
|-
| Logitech HD Webcam C270 720p
| Not required
| standard-A
| USB 2.0
| 500mA
| standard-A port
| Yes
| Yes
| ID 046d:0825 Logitech, Inc. Impressive. Works out of the box flawlessly. Audio recognized, but not tested. More info to come.
|}

===Audio devices===
----

====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
|
|
|
|
| {{Yes}}
| [http://www.gp32x.com/board/index.php?/topic/58523-zynaddsubfx/page__view__findpost__p__938432 source]
|-
| M-Audio MIDISPORT 2x2 Anniv
| Not required
|
|
| 400mA
|
| Not tested
| ID 0763:1050 Midiman. Such a current draw :/
|-
|}

====USB audio 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 in Linux
! Tested on Pandora
! Additional comments
|-
| Cakewalk UA-1G
| not required
| standard-A
| USB 2.0
| 200mA
| standard-A port
| Yes, not tested myself but widely reported to work
| Does not work yet
| ID 0582:00e9 Roland Corp. This device may be similar to older Edirol/Roland USB audio devices.
|}

===Input device===
----
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 OTG adapter/cable or a 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 in Linux
! Tested on Pandora
! Additional comments
|-
| 2-TECH SNES-to-USB adapter
| Not required
| standard-A
| Low speed
|
| standard-A port via High Speed Hub
| Yes
| Yes
| USB description is "HuiJia USB GamePad", lsusb calls it "0e8f:3013 GreenAsia Inc."
|
|-
|-
| USB Super RetroPort (SNES-to-USB adapter)
| Not required
| standard-A
| Unknown, probably USB 1.1
|
| standard-A port via High Speed Hub
| Yes
| No
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=29 RetroZone]
|
|-
| USB RetroPort (NES-to-USB adapter)
| Not required
| standard-A
| Unknown, probably USB 1.1
|
| standard-A port via High Speed Hub
| Yes
| No
| Bought from [http://www.retrousb.com/product_info.php?cPath=21&products_id=28 RetroZone]
|
|-
| Trio Linker Plus II (PlayStation,-GameCube,-and-Dreamcast-to-USB adapter)
| Not required
| standard-A
| Unknown, probably USB 1.1
|
| standard-A port via High Speed Hub
| Yes
| No
| Bought from [http://www.play-asia.com/paOS-13-71-6m-49-en-70-1zfv.html Play-Asia]
|
|-
| NAZAR V47 USB Force Feedback Vibrating Gamepad Controller for PC
| Not required
| standard-A
| Unknown, probably USB 1.1
|
| standard-A port via High Speed Hub
| Yes
| 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]
|
|-
| 10-Fire-Button Double Vibration Feedback USB PC Arcade Joystick
| Not required
| standard-A
| Unknown, probably USB 1.1
|
| standard-A port via High Speed Hub
| Yes
| 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]
|
|-
| Official PlayStation 3 controller
| Not required
| standard-A
| Full speed
|
| USB A To Mini B Cable via High Speed Hub
| Yes
| No
| This is for USB not bluetooth compatibility. Sixaxis and DualShock not tested.
|-
| Thrustmaster Firestorm Digital 3 Gamepad
| Not required
| standard-A
| Low speed
|
| standard-A port via High Speed Hub
| Yes
| 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
|
| standard-A port via High Speed Hub
| Yes
| No
| This also includes gamepads for PC that needs the Windows Xinput driver. Such gamepads include the Logitech Chillstream.
|-
| WiseGroup.,Ltd SmartJoy Dual PLUS Adapter (dual PSX to USB joypad adapter)
|
| standard-A
| Unknown
| 100mA
| Unknown
| Yes
| No
| ID 6677:8802
|}

====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
! Tested in Linux
! Tested on Pandora
! Additional comments
|-
| Bamboo Multitouch
|
|
|
|
|
| Yes
| [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__881806 Doesn't work]
|-
| Genius Tablet
|
|
|
|
|
| Yes
| [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__883140 Works via USB2 hub]
|-
| Wacom CTH-460
|
|
|
|
|
| Yes
| [http://www.gp32x.com/board/index.php?/topic/54728-pandora-owners-tried-tablet/page__view__findpost__p__924422 Doesn't work] - needs patched driver
|-
| Wacom Volito2 Tablet (Model: CTF-420)
| Not required
| standard-A
| Low speed
| 40 mA ([http://www.my-volito.com/volito/specs.asp?lang=en Source])
| Yes
| 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|No}}
| Seems to disable USB port, reboot afterwards required
|-
| Apple Mouse with Scroll Ball (A1152)
| USB
| {{No|No}}
| Seems to disable USB port, reboot afterwards required
|}

==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 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
! Tested
! 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 (like $8)
|-
| 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===
{|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
! Tested
! Additional comments
|-
| Griffin SmartShare USB
| No
| [[http://www.griffintechnology.com/products/smartshare-usb Griffin website]]
|-
| Belkin F5U415 4 Port USB 2.0 Swivel Hub
| No
| Comes with an optional power adapter. [[http://catalog.belkin.com/IWCatProductPage.process?Product_Id=377085 Belkin website]]
|-
| Belkin F5U701 USB 2.0 7 Port Mobile Hub
| Works - pabloh
| Comes with an optional power adapter. [[http://www.belkin.com/IWCatProductPage.process?Product_Id=369788 Belkin website]]
|-
| ID 0e8f:0016 GreenAsia Inc.
| Not Working - tsh
| Labeled as high speed, from ebay
|-
|Trust 4 port netbook hub ID 05e3:0608
|Works - tsh
|http://www.amazon.co.uk/gp/product/B0025X16AS
|-
| HIGH SPEED 4 PORT MINI USB 2.0 HUB FOR LAPTOP PC (non powered)
| YES
| octopus style small cheap nonpowered USB hub from ebay [[http://cgi.benl.ebay.be/ws/eBayISAPI.dll?ViewItem&item=270538502843 ebay seller]]
|-
| Logitech Premium 4-Port USB Hub
| Works
| http://www.logitech.com/en-in/notebook-products/usb-hubs/devices/3048
|-
| LUPO 7-port USB 2.0 Hub (cheap octopus type which can be powered as there is dc socket)
| Works - kilowatt
| Does not come with a power adapter, hub was tested without a power supply. [http://www.amazon.co.uk/gp/product/B003BVDABG/ref=oss_product from amazon uk seller]]
|}

==More Information==
For more information on the Pandora's two USB ports and the possible connections that can be made with them, see [[USB_reference|the USB reference page]].

[[Category:Hardware]]
[[Category:List]]

PXML specification

2011-02-27T18:27:55Z

Thomasjfox: /* Description */

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. Be aware that each element inside <application> has to be in the correct order. Files that do not pass the validation might still work as expected, but if the validation is passed you can be 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>

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

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

</application>
</source>

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

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

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

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

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

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

=== The <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 <title> element ===
==== Description ====

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

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

==== Example ====
<source lang="xml">
<title lang="en_US">Your application name</title>
<title lang="de_DE">Dein Programmname</title>
</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 '-'.
==== Example ====
<source lang="xml">
<version major="1" minor="1" release="1" build="2"/>
</source>

=== The <osversion> element ===
==== Description ====

The osversion element specifies the minimal OS version that supports the PND file. The PND file will not be loaded by an OS that has an older version than the one specified here.
An osversion element is optional. It is recommended to keep the entries as simple as possible, where possible just numbers. It accepts the same attributes as the version element. All four entries are required here, too.

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

=== The <description> element ===
==== Description ====

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

The "description"-element is optional, though it is highly recommended to specify at least one for "en_US" ( American English language). Several of those elements are allowed, one for each lang that you want to display.
==== Example ====
<source lang="xml">
<description lang="en_US">Your long description of this application, describing its purpose and highlighting its features.</description>
<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und seine wichtigsten Features beschreiben sollte.</description>
</source>

=== The <icon> element ===
==== Description ====

The icon element should specify a nice icon for your program. 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 <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.

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

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

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 file ==
Please see the [[PXML_archetype|PXML archetype]].

== Validation ==

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

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.

'''Attention''': To have the PXML pass evaluation you have to put the following files in *exactly* this order using the cardinally mentioned below:
# =1 <exec>
# >=1 <title>
# =1 <author>
# =1 <version>
# <=1 <osversion>
# >=0 <description>
# <=1 <icon>
# <=1 <previewpics> (subentries!)
# <=1 <info>
# =1 <categories>
# <=1 <associations> (subentries!)
# <=1 <clockspeed>

[[Category:Development]]
[[Category:Official OpenPandora Development]]
[[Category:PND]]