Supported third-party applications and protocols

The usblauncher service supports several third-party applications and protocols for accessing content on attached devices. To work with these applications and protocols, you can define configuration rules that swap the role of the USB stack, probe a device for its iAP2 protocol support, or request a device to switch to another mode.

Enabling Apple CarPlay

To support Apple CarPlay, you must define both the Host_Stack and Device_Stack rules. Also, your system must be running the USB stack when the Apple device (e.g., an iPhone 5) is first connected, so usblauncher can learn of the connected device. If you're running the stack in host mode, you must restart it in device mode. To enable this role swapping, add the RoleSwap_DigitaliPodOut flag to the matching rule for Apple devices (which have a vendor ID of 0x05AC):

product(0x05AC, 0x1200, 0x12FF) {

    RoleSwap_DigitaliPodOut;

    -- drivers below are matched when the role swap request fails
    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
        driver"io-audio -dipod busno=$(busno),devno=$(devno),\z
                cap_name=ipod-$(busno)-$(devno)";
    };
    class(USB_CLASS_HID) {
        driver"io-fs-media -dipod,$(IPOD_OPTS)";
    };
};
Note: To obtain the drivers needed to support iOS in automotive systems, contact your Project Manager or QNX customer support.

In the failure-handling section of this rule, the HID class must specify a driver or script so that usblauncher can execute the role-swap request specified above. If you don't want your system to support Apple devices when continuing to run as the USB host after a failed role-swap request, insert a "stub" command such as "echo HID for iPod" within the HID class rule.

If you provide descriptor overrides by defining the Device_Stack.descriptors list, usblauncher will use the descriptors from the second item in this list to override the device stack's internal settings when restarting the USB stack in device mode after successfully processing the RoleSwap_DigitialiPodOut flag.

Enabling iAP2 in client mode

To support iPod Accessory Protocol 2 (iAP2) in client mode, you must define the Host_Stack and Device_Stack rules and launch the USB stack before connecting any devices that support iAP2 for playback control. To verify that a device supports iAP2 and request the necessary role-swapping of the USB stack, add the RoleSwap_AppleDevice flag to the matching rule for Apple devices:

product(0x05AC, 0x1200, 0x12FF) {

    RoleSwap_AppleDevice;

    -- drivers below are matched when the role swap request fails
    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
        driver"io-audio -dipod busno=$(busno),devno=$(devno),\z
                cap_name=ipod-$(busno)-$(devno)";
    };
    class(USB_CLASS_HID) {
        driver"io-fs-media -dipod,$(IPOD_OPTS)";
    };
};

In the failure-handling section of this rule, the HID class must specify a driver or script so that usblauncher can execute the iAP2 probe and role-swap request specified above. If you don't want your system to support Apple devices when continuing to run as the USB host after a failed verification of iAP2 support or a failed role-swap request, insert a "stub" command such as "echo HID for iPod" within the HID class rule.

If you define the Device_Stack.descriptors list, usblauncher will use the descriptors from the first item in this list to override the device stack's internal settings when restarting the USB stack after successfully processing the RoleSwap_AppleDevice flag.

Probing for iAP2 support

The Probe_iAP2 flag doesn't trigger a role-swap request but allows you to probe a device for its iAP2 support. For example, you may want to start a different driver depending on the iAP version supported:

product(0x05AC, 0x1200, 0x12FF) {

    Probe_iAP2;

    -- drivers below are matched when iAP2 isn't supported
    -- in client mode on the target
    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL) {
        driver"io-audio -dipod busno=$(busno),devno=$(devno),\z
                cap_name=ipod-$(busno)-$(devno)";
    };
};

Using multiple flags

You can use combinations of these role-swapping and device-probing flags. Their order has no significance, because usblauncher always processes the flags in this sequence:

  1. RoleSwap_DigitaliPodOut
  2. Probe_iAP2
  3. RoleSwap_AppleDevice
Note: The RoleSwap_AppleDevice flag triggers a probe for iAP2 support on the connected device, before the actual role-swapping is attempted, so the Probe_iAP2 is ignored if it's specified when this role-swapping flag is also specified.

If an iAP2 probe is attempted but no role swap happens, either because it wasn't requested or because the device doesn't support iAP2, the device object will contain the iap attribute. This attribute will be set to 2 if iAP2 support was confirmed or -1 if iAP2 isn't supported or the probe failed.

Launching a driver in host mode for Apple devices

You can define a custom function to choose between launching iAP1 or iAP2 drivers in host mode, based on the result of an iAP2 probe. This function can read the device object's iap attribute (which is set when the device is probed) and then generate a driver command based on that attribute's value:

product(0x05AC, 0x1200,0x12FF)
{
    Probe_iAP2;

    class(USB_CLASS_AUDIO, USB_AUDIO_SUBCLASS_CONTROL)
    {
        driver"io-audio <full options>"
    };
    class(USB_CLASS_HID) {
        custom = function(obj)
            if obj.EXTRA and obj.EXTRA:find('iap::2') then
                return "mm-ipod <put the full options here>";
            else -- for iAP1
                return "io-fs-media <put the full options here>";
            end
        end;
        driver"$(custom)";
    };
}

The Lua interpreter evaluates the function when expanding the driver"$(custom)" string, and then passes the resulting string to usblauncher, which executes it to launch the driver.

Enabling MirrorLink

The MirrorLink solution lets you access applications on devices such as smartphones through a car infotainment system. To enable MirrorLink on an attached USB device, usblauncher can send that device a request to switch to a Network Configuration Management (NCM) personality. To support this MirrorLink command, you must define a table in the configuration file as follows:

MirrorLink = {
    version = 0x0101,
    vendor_id = 0xABAB,
    blacklist = {
        { vid = 0x0781; did = 0x74e0 }; -- SanDisk Sansa Fuze+
        { vid = 0x0951; did = 0x1624 }; -- Kingston DataTraveler G2
        { vid = 0x05ac;              }; -- any Apple device
    };
    timeout = 2000,
    ignore  = false,
    stall_reset = false
}

This table provides the field values for the MirrorLink command to enable the NCM personality. The version and vendor_id fields are two-byte integers. Each item in the blacklist list can be simply a vendor ID (vid) or both the vid and device ID (did). You should add blacklist items for all devices not suitable for MirrorLink; these devices won't receive requests to switch to an NCM personality.

The timeout field specifies how long to wait, in milliseconds, for a response to the MirrorLink command to enable NCM on a device. It also specifies how long to wait for a device that accepts the MirrorLink command to leave the bus.

Normally, a device leaves the bus and comes back with an NCM personality; however, some noncompliant USB devices may respond successfully to the MirrorLink command to enable NCM but they may never leave the bus. In this latter case, the timeout determines how long usblauncher waits before continuing to match and launch any drivers for devices that haven't left the bus.

You can set the ignore field to true to prevent usblauncher from matching the NCM interface to a driver rule, which would select a configuration and launch a driver for that interface. The ignore setting is useful if you're running a resident driver outside of usblauncher that manages the NCM interface.

Note: If you do use usblauncher to start a driver for the NCM interface, you don't need to restart the USB stack in device mode (unlike when supporting CarPlay). For MirrorLink, the car infotainment system remains the USB host.

Setting stall_reset to true enables resetting the device if it responded with the USB STALL packet. Some devices don't behave correctly unless they're reset in this case.