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

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

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.