Home
Developer Resources
Technical Articles

QNX Technical Articles

QNX Apps and Media Interface for Apple iPod 1.1: Installation Note

QNX Apps and Media Interface for Apple iPod 1.1: Installation Note

Electronic edition published: Thursday, April 9, 2015

This package delivers the additional binaries and libraries required to support Apple iPod integration with QNX SDK for Apps and Media 1.1.

Note: Before you install this archive, you should already have installed the following on your host:
  • QNX Software Development Platform 6.6
  • QNX SDK for Apps and Media 1.1

Host OS

You can install this package on one of the following development hosts:

  • Microsoft Windows 8 Professional 64-bit, Windows 7 Professional 64-bit, or XP Professional SP3
  • Red Hat Enterprise Linux 6 64-bit or Ubuntu Workstation LTS 12.04 32- and 64-bit

What's in the Installation Note

For instructions on: See:
Obtaining an authentication chip required for using the iPod interface Authenticating the iPod interface
Installing the iPod interface on QNX SDK for Apps and Media 1.1 Installing the archive
Reconfiguring the multimedia components to support iPods Enabling iPod support in multimedia components
Finding the iPod files to add to the target image Adding iPod support to the target image
Verifying that the target recognizes Apple hardware Testing iPod support on the target
Accessing iPod documentation Documentation for the iPod interface

Authenticating the iPod interface

The iPod interface requires authentication before commands can be sent to iPod Touch, iPad, and iPhone devices. The Apple Authentication Coprocessor can be purchased from Apple when a valid licensing agreement has been signed.

QNX does not supply such authentication hardware to customers. Please contact Apple directly to obtain an Apple Authentication Coprocessor for evaluation, demonstration, or production use.

You must integrate this hardware into your board. For suggestions on integrating the Apple authentication hardware, contact QNX technical support.

Installing the archive

To install the iPod interface:

  1. Log into your myQNX account on our website, then go to the Download area.
  2. Download the archive ipod-datestamp.zip.
  3. Verify that the checksum of the package matches the one given in the Download area.
  4. Unzip the archive into your base_directory, which is the directory where you install QNX SDP 6.6:
    • On Linux:

      unzip ipod-datestamp.zip -d base_directory

    • On Windows, use WinZip.
  5. Copy the contents of the base_directory/deployment directory into $QNX_DEPLOYMENT_WORKSPACE, which is the same directory you set up for building your target images (see the instructions in the "Building a target image" section of the Getting Started guide).

Enabling iPod support in multimedia components

The multimedia components in the QNX SDK for Apps and Media are designed to work with Apple devices but you must reconfigure them to enable their iPod-supporting features. To work with Apple devices, you must reconfigure these components:

  • In the main usblauncher configuration file (by default, QNX_TARGET/etc/usblauncher/rules.lua), ensure that you have the following rule:

    product(0x05AC, 0x1200, 0x12FF) {
        -- First, we check whether the latest device supports iAP2
        Probe_iAP2;
    
        class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
            driver"io-audio -dipod busno=$(busno),devno=$(devno),cap_name=ipod-$(busno)-$(devno)";
        };
    
        class(USB_CLASS_HID) {
            -- Define a custom function to generate an iAP1 or iAP2
            -- driver command in host mode, based on the result of the
            -- Probe_iAP2 operation. If this operation isn't enabled,
            -- the function will generate the iAP1 driver command.
            custom = function(obj)
                -- you may need to change the i2c addr= and path= to
                -- match your particular board configuration
                if obj.EXTRA and obj.EXTRA:find('iap::2') then
                    -- for iAP2
                    return "mm-ipod -diap2,config=/etc/mm/iap2.cfg,\z
                            ppsdir=/pps/services/multimedia/iap2-$(busno)-$(devno) \z
                            -ai2c,addr=0x11,path=/dev/i2c99 -tusbhost,busno=$(busno),devno=$(devno),\z
                            path=/dev/io-usb/io-usb,audio=/dev/snd/ipod-$(busno)-$(devno)";
                else
                    -- for iAP1
                    return "io-fs-media -dipod,pps=/pps/services/multimedia/iap1-$(busno)-$(devno),\z
                            transport=usb:busno=$(busno):devno=$(devno):path=/dev/io-usb/io-usb:\z
                            audio=/dev/snd/ipod-$(busno)-$(devno),\z
                            darates=+8000:11025:12000:16000:22050:24000,playback,\z
                            acp=i2c:addr=0x11:path=/dev/i2c99,config=/etc/mm/ipod.cfg";
                end
        	end;
        	driver"$(custom)";
        };
    
        -- Ignore all other interfaces
        interface(0,127) {
        	Ignore;
        };
    };

    The usblauncher service enumerates USB devices and launches drivers for communicating with them. By defining the above rule, you can instruct the service about which driver setup to use when an Apple device is connected, depending on whether the device runs iAP1 or iAP2. Note the vendor ID (0x05AC for Apple) and range of product IDs (0x1200 to 0x12FF, which covers all Apple devices that run one of these protocols).

    Further information on probing for iAP2 support and on defining USB matching rules can be found in the "Supported third-party applications and protocols" section of the Device Publishers Developer's Guide.

  • In the QNX_TARGET/etc/mm/mm-sync.conf file, change this:

    <MSS>
        <!-- <dll name="mss-ipodgeneric.so"/> -->
        <!-- <dll name="mss-ipodpb.so"/> -->
        <!-- <dll name="mss-ipoduid.so"/> -->
        <!-- <dll name="mss-ipodiap2.so"/> -->
    </MSS>
    to this:
    <MSS>
        <dll name="mss-ipodgeneric.so"/>
        <dll name="mss-ipodpb.so"/>
        <dll name="mss-ipoduid.so"/>
        <dll name="mss-ipodiap2.so"/>
    </MSS>

    This enables the iPod synchronizers used by the multimedia synchronizer service, mm-sync, so you can upload media metadata from Apple devices to persistent storage.

  • In the QNX_TARGET/etc/mm/mm-md.conf file, change this:

    #[plugin]
    #dll=mm-mdp-ipod.so

    to this:

    [plugin]
    dll=mm-mdp-ipod.so

    Next, change this:

    [typeratings]
    file=mmf
    #file=mmf,exif,img
    http=mmf
    cdda=cdda
    rtsp=mmf
    #ipod=ipod
    #mtp=mediafs

    to this:

    [typeratings]
    file=mmf
    #file=mmf,exif,img
    http=mmf
    cdda=cdda
    rtsp=mmf
    ipod=ipod
    #mtp=mediafs

    This enables the iPod plugin for the metadata provider library, libmd. This plugin reads metadata from media files on Apple devices and is used by mm-sync in the information upload process.

Adding iPod support to the target image

You must regenerate the target image to include the iPod libraries and binaries shipped with this package. All the iPod files that you must add to the image are explained in the iAP1 Drivers and Utilities and iAP2 Drivers and Utilities chapters of the Working with iPods document, also included in this package.
  1. Add the fileset basefs.mm.extra.ipod.xml to your board's profile. In the file $QNX_DEPLOYMENT_WORKSPACE/infra/product/AnM/board_variant/os.xml, add the line
    <include-fileset name="basefs.mm.extra.ipod.xml "/>
    to the basefs package section. This is usually at the top of the file.
  2. Rebuild your target image to include the files shipped with this package. For full instructions for building target images, see the Getting Started guide.

Testing iPod support on the target

After deploying the updated image onto your target, you should verify that the target system can recognize the Apple authentication hardware and any Apple devices when they're connected.

For iAP1 devices (e.g., iPod Classic, iPhone 4), do these steps:

  1. Ensure that the Apple Authentication Coprocessor is available:
    # ls /dev/i2c99
    /dev/i2c99
  2. Ensure that the correct drivers are started. When you insert an iAP1 device, the usblauncher service should start the io-fs-media and io-audio drivers:
    # pidin a | grep io-fs-media | grep ipod
     1843253 io-fs-media -dipod,transport=usb:busno=0:devno=0x5:audio=/dev/snd/ipod-0-0x5,
                         darates=+8000:11025:12000:16000:22050:24000,playback,
                         acp=i2c:addr=0x11:path=/dev/i2c99,fnames=short,config=/etc/mm/ipod.cfg,stalk
    # pidin a | grep io-audio | grep ipod
     1843252 io-audio -dipod busno=0,devno=0x5,cap_name=ipod-0-0x5
  3. Check that the device address appears at the expected device path:
    # ls /dev/snd/ipod*
    /dev/snd/ipod-0-0x5
  4. Check that the mounted device has a device path listing:
    # ls /fs/ipod*
    /fs/ipod0
  5. Test playback from the iAP1 device. Using the mmrplay tool, you can direct the device output to the preferred audio device, by running:
    # mmrplay -A mmf.MM_AUDIO_STREAMER_RDDATAINPAUSE=1 -a "snd:/dev/snd/pcmPreferredp"
              "snd:/dev/snd/ipod-0-0x5" > /dev/slog2/debug 2>&1 &
  6. Test database navigation and the play command. Using the ipodcli utility, you can access the iPod database engine and keep selecting more specific categories (e.g., artist, album, track) until you select an individual song or video to play. Full documentation on ipodcli is found in Working with iPods.

For iAP2 devices (e.g., iPod Touch 5G, iPhone 5), do these steps:

  1. Ensure that the Apple Authentication Coprocessor is available:
    # ls /dev/i2c99
    /dev/i2c99
  2. Ensure that the correct drivers are started. When you insert an iAP2 device, the usblauncher service should start the mm-ipod and io-audio drivers:
    # pidin a | grep mm-ipod | grep ipod
      643119 mm-ipod -diap2,config=/etc/mm/iap2.cfg,ppsdir=/pps/services/multimedia/iap2-0-0x4
                     -ai2c,addr=0x11,path=/dev/i2c99 -tusbhost,busno=0,devno=0x4,
                     path=/dev/io-usb/io-usb,audio=/dev/snd/ipod-0-0x4
    # pidin a | grep io-audio | grep ipod
      643118 io-audio -dipod busno=0,devno=0x4,cap_name=ipod-0-0x4
  3. Check that the device address appears at the expected device path:
    # ls /dev/snd/ipod*
    /dev/snd/ipod-0-0x4
  4. Check that the mounted device has a device path listing:
    # ls /dev/ipod*
    /dev/ipod0
  5. Test playback from the iAP2 device. Using the mmrplay tool, you can direct the device output to the preferred audio device, by running:
    # mmrplay -A mmf.MM_AUDIO_STREAMER_RDDATAINPAUSE=1 -a "snd:/dev/snd/pcmPreferredp"
              "snd:/dev/snd/ipod-0-0x4" > /dev/slog2/debug 2>&1 &
  6. Test starting and stopping playback, skipping to another song, and retrieving album art on the device. Using the iap2cli utility, you can send playback commands to the iAP2 device and extract the artwork for the current song. Full documentation on iap2cli is found in Working with iPods.

Documentation for the iPod interface

The Working with iPods document comes in two forms:

  • A PDF document, found in base_directory/target/qnx6/usr/help/pdf/ after you unpackage the archive.
  • An HTML document, added to the help file in the QNX Momentics IDE. The HTML content is actually copied to base_directory/target/qnx6/usr/help/eclipse/plugins/, which is the directory used by the IDE for storing the help file plugins.