Pandora Wiki - User contributions [en]

PND:FAQ

2010-03-07T16:43:39Z

Aninhumer: Moved all advanced questions to a separate section

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

==The PND system==

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

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

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

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

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

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

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

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

==Usage==

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

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

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

==Advanced Information==

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

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

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

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

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

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

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

PND:FAQ

2010-03-07T12:00:10Z

Aninhumer: /* How is a PND file structured? (Advanced) */

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

==The PND system==

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

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

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

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

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

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

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

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

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

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

==Usage==

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

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

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

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

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

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

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

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

PXML specification

2009-11-02T17:36:56Z

Aninhumer: Added source tags, still needs headings and other formatting tweaks

'''This is taken from the HTML version included in the libpnd distribution; the HTML formatting therein may be perverted during import to this wiki.'''

The PXML file format specification
Introduction

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

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

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

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:

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

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

The PXML-tag serves as the container for all PXML elements. It is the first thing that should occur in your PXML file. An example "<PXML>"-tag would look like this:

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

</PXML>
</source>

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

The "xmlns" attribute is required by the XML standard, and guarantees that this file will be identified as a PXML file. You must include the xmlns attribute, exactly as shown, in your PXML file, with the URL as specified. Only then can it be guaranteed that the file will be read at all by launchers and menu apps.

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

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

At least one "title"-element is required, in the "en_US" American English language.
Example
<source lang="xml">
<title lang="en_US">Your application name</title>

<title lang="de_DE">Deinen Programmnamen</title>
</source>
The description element
Description

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

At least one "description"-element is required, in the "en_US" American English language.
Example
<source lang="xml">
<description lang="en_US">Your long description of this application, describing it's purpose and highlighting it's features.</description>

<description lang="de_DE">Deine etwas längere Programmbeschreibung, die den Sinn des Programmes und den wichtigsten Features beschreiben sollte.</description>
</source>
The exec element
Description

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

The command attribute specifies the path to the executable file. This should be a relative path to a file within the PND package.

The startdir attribute specifies the starting directory Also known as the working directory that the application should start in. This should be a relative path to a directory within the PND package, or to a well-known directory in the Pandora file system.

The standalone attribute specifies wether 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.

The background attribute specifies wether 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.
Example
<source lang="xml">
<exec background="true" startdir="/usr/share/icons/" standalone="true" command="./myprogram"/>
</source>
The icon element
Description

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

The src attribute specifies the path to the image file used as the icon.
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.

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

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

The name attribute specifies the name of the author.

The website attribute specifies the website of the author.

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

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

The major attribute specifies the major version number. This number should be 0 or more.

The minor attribute specifies the minor version number. This number should be 0 or more.

The release attribute specifies the release number. This number should be 0 or more.

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

The osversion element specifies the application version.
An osversion element is optional. It accepts the same attributes as the version element.
Example
<source lang="xml">
<osversion major="1" minor="1" release="1" build="2"/>
</source>
The categories element
Description

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

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

1. Development
2. Education
3. Games
4. Graphics
5. Internet
6. Multimedia
7. Office
8. Settings
9. System
10. Utilities

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 any name for your subcategory.
Example
<source lang="xml">
<categories>
<category name="Games">
<subcategory name="Strategy"/>
<subcategory name="Turn-based"/>
</category>
<category name="Graphics">
<subcategory name="Image Editors"/>
</category>
</categories>
</source>
The associations element
Description

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

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

The name attribute on an association element specifies the user-friendly action name for the association.

The filetype attribute on an association element specifies what file types (in MIME format) that this association should apply to.

The exec attribute on an association element specifies the command-line arguments that should be given to the program, when this action is performed. The exec can contain a "%s", which indicates where the file name of the file, that the action is performed on, should be inserted.
For example, if the exec-line is "--file %s --type lol", and you have a file "lol.bmp" that the action is performed on, the exec-line is transformed into "--file "lol.bmp" --type lol"
Example
<source lang="xml">
<associations>
<association name="Open Bitmap Image" filetype="image/bmp" exec="-f %s --no-deinterlacing"/>
<association name="Crash the computer with a stylesheet" 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.
A clockspeed element is optional. It accepts the following attributes:

The frequency attribute specifies the wanted frequency, in megahertz mHz.
Example
<source lang="xml">
<clockspeed frequency="600"/>
</source>
Example file
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<PXML id="youruniqueID" xmlns="http://openpandora.org/namespaces/PXML">
<title lang="en_US">Program Title</title>
<title lang="de_DE">German Program Title</title>

<exec background="true" startdir="/usr/share/icons/" standalone="true" command="./program"/>

<icon src="./program.png"/>

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

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

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

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

<categories>
<category name="Main category">
<subcategory name="Subcategory 1"/>
<subcategory name="Subcategory 2"/>
</category>
<category name="Alternative category">
<subcategory name="Alternative Subcategory 1"/>
</category>
</categories>

<associations>
<association name="View Word File" filetype="application/msword" exec="-f %s -t doc"/>
</associations>

<clockspeed frequency="600"/>
</PXML>
</source>

Validation

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

You will also need to put the XML schema for the PXML format in the same folder as your PXML file.

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

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

Now the PXML file can be validated.

USB reference

2009-10-25T20:56:41Z

Aninhumer: /* So which devices are USB 1.1, and which ones are USB 2.0? */ Not sure webcams are 1.1

==Readme First!==

If you have a question to ask, that isn't covered in this FAQ already, please ask over on the [http://www.gp32x.com/board/index.php?showforum=61 Forums].

==USB FAQ==

===How many USB ports does Pandora have?===
Pandora has two USB ports:
* 1x USB 2.0 host port (USB standard-A receptacle)
* 1x USB 1.1/2.0 OTG port (USB mini-AB receptacle)

===What does “host port” mean?===
A USB host port “hosts” any device that you plug in, just like the USB ports on your computer. Pandora’s full size USB A port can host USB 2.0 devices, and provide up to 500mA (the maximum allowed according to USB standards).

===What does “OTG” mean?===
OTG stands for On The Go. USB OTG ports can operate in two different modes. When connected through this port, the Pandora can act as a device, for example when connected to a computer for charging & data transfer. For this mode, you need a standard-A to mini-B cable. However, the Pandora can also act as a host port for USB 1.1 and USB 2.0 devices. For details on how to make the necessary cable connection, see [[USB_reference#OTG_host_mode|the OTG host mode section]]. This port can supply a maximum of 100mA in host mode. Although this port implements On The Go functionality, it can not get an official On The Go certification because the OTG specification requires a device to have exactly one USB port. (The Pandora has two.) Also, the mini-AB connector used on the Pandora has been taken out of the specification in 2007 (but is still widely adopted).

===What’s all this stuff about USB 1.1 and USB 2.0? Isn’t USB, uh, universal?===
The USB 2.0 protocol is not backwards compatible with USB 1.1. Most USB ports (eg. on your computer’s motherboard, in USB hubs) actually contain two chips to allow universal compatibility – one for USB 1.1, and one for USB 2.0.

Pandora’s USB standard-A host port does not contain this second chip. Only USB 2.0 devices bearing the “USB HIGH SPEED” logo can be plugged directly into this port. However, USB 1.1 devices can be connected to this port through a USB hub, provided the hub bears the “USB HIGH SPEED” logo.

Pandora’s USB OTG (mini-AB) port is fully compatible with both USB 1.1 and USB 2.0, allowing it to host either type of device.

===So which devices are USB 1.1, and which ones are USB 2.0?===
[[Image:USB-HighSpeed-certified-Logo.png|thumb|alt=USB High Speed Certified logo|Devices bearing this logo are certified High Speed devices. They can be plugged directly into Pandora's USB 2.0 host port.]]
There are no set rules. As a very general guide:
* Common USB 1.1 devices include keyboards, mice, headsets, older USB devices.
* Common USB 2.0 devices include cameras, PMPs, HDDs, hubs, card readers, thumb drives.
This is just a rough representation of what’s out there in the wild, and you will find exceptions. Devices like HSDPA modems and GPS units could fall into either category. The only reliable indication of true USB 2.0 compatibility is the “USB High Speed Certified” logo (right).

===Arrgh, USB used to be simple. What can I actually connect to Pandora?===
Almost anything, as long as it's supported by Linux. Think of a USB device that everybody uses (mouse, keyboard, thumb drive...) and chances are it will be a simple matter of plug and play. But this might not be the case for more specialised USB devices (modems, ethernet adapters, USB displays...), many of which will only function with Windows specific drivers.

If you intend to purchase USB accessories for use with Pandora, you should first research Linux support for that type of device. Devices already tested on Pandora will be added to the [[USB compatibility list]].

The various USB connection scenarios are as follows:

==Pandora as USB slave==
[[Image:Pandora.usb.slave.png|thumb|alt=Pandora as USB slave|Pandora as USB slave]]
Using a USB standard-A to mini-B cable (the kind you probably own several of), you can:
* Transfer data to/from Pandora
* Charge Pandora's battery.

'''Note:'''
*Charging Pandora from your computer's USB port is best done with Pandora in standby mode, or switched off. The current provided by your computer will probably not be sufficient to provide an effective charge while Pandora is being used.

==Hosting USB devices==
[[Image:Pandora.usb.host.png|thumb|alt=Pandora as a USB host|Pandora as a USB host]]
*Directly plug in a USB 2.0 device such as a thumb drive, or a Huawei E160 modem.
*Using a USB standard-A to USB standard-B (or mini-B, micro-B, depending on what's on the device) cable, connect USB 2.0 devices such as cameras, PMPs, and HDDS.
*Connect a USB hub, which will enable you to to connect USB 1.1 devices such as keyboards, mice, or a Huawei E220 modem.

'''Note:'''
*This port can supply a maximum of 500mA. If you plan to use a USB HDD, note that very few of these can draw sufficient power from a single USB port. A powered HDD caddy or powered USB hub will be necessary in most cases.

==OTG host mode==
[[Image:Pandora.usb.otg.host.png|thumb|alt=Pandora in OTG host mode|Pandora in OTG host mode]]
How you connect a device to the mini-AB OTG port depends on the device's USB connector.
*standard-B receptacle: Use a mini-A to standard-B cable.
*mini-B receptacle: Use a mini-A to mini-B cable.
*micro-B receptacle: Use a mini-A plug to standard-A receptacle adapter and a standard-A to micro-B cable.
*standard-A plug: Use a mini-A plug to standard-A receptacle adapter.
*mini-A plug: No extra cable or adapter needed.
*micro-A plug: No standardized solution exists.

This port allows you to connect a USB 1.1 device directly, without the use of a hub. This port is also USB 2.0 compliant.

'''Notes:'''
*mini-A and mini-AB connectors have been removed from the present USB standard. This means that the above connectors may vanish from the market at some point (although there will probably be demand for them for some time). There are a lot of connectors available that were never standardized. It is recommended that you do not use them as they may lead to non-working connections. Stick to the cables and adapters mentioned above and look for a mention of "OTG" or "On The Go" and you should be on the safe side.
*In host mode, this port can supply a maximum of 100mA. USB 1.1 devices that draw more than 100mA will need to connect to Pandora's other USB port via a hub, as depicted in the previous example. The Huawei E220 is one such device.

==Links==
*[[USB_compatibility_list|Pandora USB compatibility list]]
*[http://www.usb.org/developers/docs/usb_20_122208.zip USB 2.0 Standard (including present OTG spec)]
*[http://www.usb.org/developers/onthego/otg1_0.pdf Original OTG Specification defining mini-A and mini-AB and allowed connections]
*[http://www.usb.org/developers/Deprecation_Announcement_052507.pdf mini-A and mini-AB Deprecation Announcement]
*[http://en.wikipedia.org/wiki/USB Wikipedia page on USB]

[[Category:FAQ]]