ADC Membership Technical Business Join ADC
Search Advanced Search
Technical Note TN1191
USB Software Locator

CONTENTS

This Technote describes the live software update process under Mac OS 9.0 and the support that it provides for USB devices. It further explains the enhancements provided under Mac OS 9.0.4 to make installer development simpler. It details how developers can register with DTS to have access to the USB Update Database. The developer updates this database to provide information that the Software Update process uses to download the appropriate software for the USB Device.

 Updated: [Feb 23 2001]






Software Update Process Overview

Software Update, a new feature provided in Mac OS 9, makes it possible for system software to be updated over the Internet as newer software is made available. At present this feature is limited to Apple system software. A derivative of this functionality has been provided for USB devices: finding a driver for an unrecognized USB Device. This means that if a USB device is attached for which there is no recognized driver, Software Update will ask the user to search for the necessary driver on the Internet. If a suitable driver is registered, the software package is downloaded.

For USB developers, there are six important aspects toward implementing support of Software Update for their products:

  1. Registering with DTS to enable access to the USB Software Update Web page;

  2. Entering the device data into the USB Editor staging server database along with the URL to your web server where the software will be downloaded;

  3. Packaging your software so that it can be installed properly;

  4. Using the Software Locator Switch to set Software Update to search the USB Editor staging server database;

  5. Testing the USB Software Locator process by connecting a USB device when no USB driver is present to support the device; and

  6. Setting the USB Editor database record to move the record to the production server.

Note that the current implementation only supports finding driver modules over the Internet when no matching driver can be found on the host system. There is no support at this time for updating existing USB driver software, or for finding "better" USB driver software. In addition, there is no support by Software Update for other types of third-party software except for USB. Another limitation is the availability of the Software Update process for Mac OS 9.0 and later only. There is no support for Software Update in earlier releases of the Mac OS.

For Mac OS 9.0.4, Software Update was enhanced to recognize Disk Copy images. This feature made it possible for the use of a third-party installer to be used with the USB Software Locator process.


Back to top

USB Software Locator Process Description

When the user attaches a USB device to the Macintosh, Mac OS USB searches the ROM and the Extension folder for an 'ndrv' driver file whose DriverDescription record matches the characteristics of the device. If no matching driver is found, the following alert is displayed under Mac OS 9.0 or greater:

tn1191.1.gif

Note the difference in wording between this alert and similar alerts provided under previous releases of Mac OS. Under Mac OS 9, the user is given the option to have the system search the Internet for a driver to support the device. If the user clicks the OK button, the system will access the Internet to find the Apple USB database web page. If the web page can be accessed, then Mac OS USB searches for an entry in the USB database matching the Vendor ID, Product ID, device class, and subclass. If a matching entry is found, the user is presented with the following alert:


tn1191.2.gif

In the above example, only one software package was found. It could be that there are several software packages available for a device. In such case, all matching selections are presented to the user. The user can click on any software package listing and read the associated description in the lower window pane in order to choose the appropriate software.

The user has the option to download the selected software. If the user chooses to install the software, Software Update uses the URL specified in the USB database to download it. If the downloaded file is an Apple Installer Script, then the script is executed. Under Mac OS 9.0.4 and greater, if the downloaded file is a Disk Copy image, the image is mounted, then Software Update looks in the Disk Copy image for an Apple Installer script document and opens it with the Installer Engine. If the downloaded file is any other file, then the file is placed into the developer-specified location, typically the Extension folder. Once the file is downloaded, Software Update tells USB to re-scan for a USB driver to support the device. Note that while a USB driver module may get matched, there may be other processes that need to be activated, or installed, which may require the computer to be restarted.

The Apple USB Database is password-accessible at the Apple USB Editor Web page. Developers must register with DTS to be able to access database records based on their USB Vendor ID. It is important that your device implement your vendor ID.


Back to top

Registering With DTS

The Software Update process begins by contacting Worldwide Developer Technical Support and submitting:

  1. AppleConnect/Directory Services ID

  2. Your name and company

  3. The USB Vendor ID's for which you request access

After submitting this information, you can access the Apple USB Editor Web page. The USB Editor Web page is a staging server where you enter the Software Update information needed to find the USB software for your device, and verify that the locator process works as advertised. After the registration is approved, you can access the USB Editor Web Page to add, modify, or delete database entries associated with your vendor ID. For security reasons, we require that your Apple Connect ID be associated with the Vendor ID for which you are requesting access. If the ID does not match, we will require that you have the official vendor ID owner access the USB Editor database and provide the information on where to access your software.

DTS understands that many developers are writing USB software for devices which have vendor ID's associated with a different developer. The current design of the USB Editor web page was based on the assumption that there would be only one developer accessing all records associated with each vendor ID. If multiple accounts accessed a vendor ID, they would have access to all records associated with the vendor ID. For this reason, we are limiting access for each vendor ID records to the developer assigned that ID. At some point in the future, we hope to have a better solution.

Back to top

Using the USB Editor Web Page

The information that you enter into the USB Editor Web page is sent to a staging server. Any information which you enter will only be available to you and others who have the Software Locator Switch application to have Software Update use the staging server instead of the production server. This allows you to test the Software Update process prior to making it live.

At the Apple USB Editor Web page, enter your account name and password. You are presented with the database page for your vendor ID. The present Apple entry is shown below:

tn1191.3.gif

Use the "Add Device" link to define a new Device. Use the "Add Software Package" to define the software for the device. You can provide localized software that will be presented to the user based on the country code value associated with the active system software. Use the "Add Description" link to set a user-visible description for the software package, which Software Update displays to the user.

Add Device

The Add Device link takes you to a web page as shown below. Use this page specify the characteristics of your device, which the USB Software Locator will use to match a supported device:

tn1191.4.gif

The vendor field will be filled in by the system and should be the name of your company. You are required to enter the Device Name, USB Device Subclass, and Product ID. You must also set the USB Class popup menu to match the device class of your device. The Protocol and Version fields are annotated with an asterisk. These fields are optional. Click the "Save" button to have this information saved in the Apple database. Click the "Cancel" button if you don't want the information saved.

The Device Name is used in the "Add Software Package" page to associate the software package with a device. The Device Name is identical to the product name displayed to the user in the Software Update process.

If your device class is not displayed in the popup menu, please submit a note to Developer Technical Support, and indicate the device class name and value.


Back to top

Add Software Package

Once you have defined the device and saved this information, return to the device web page and click the "Add Software Package" URL to take you to the following page:

tn1191.5.gif

The fields and popups on this web page, which have no explanation, are used as follows:

Device popup - select the device for which this software package is used. You can select only among those devices which have been previously defined.

Last Changed on Field- indicates the most recent modification date for this record.

Last Moved to Production on Field - indicates when this record was last moved to the production server.

Move To Production popup - indicates whether the updates/changes to the record will be moved to the production Software Update server. Set to "Y" to have the record moved to the Production Server. The changes are checked once a day. Allow 24 hours before your changes become live. While you are editing and testing the Software Update support for your device, set this popup to "N". When you are satisfied that the correct software package has been identified for the device, and will be installed properly by Software Update, set the popup to "Y".

Enclosed File Name Field - as indicated, this is the name of the de-BinHexed file. If the file is an Installer Script with the file type and creator 'kajr', then Software Update will execute the Installer script. For the script to work properly, the associated tome file must be merged into the script. Refer to the section Installing USB Shims and other related software below, to understand how to activate a USB shim without forcing a reboot.

For Mac OS 9.0.4, Software Update supports MacBinary-encoded files, as well as BinHexed-encoded files. This release also supports Disk Copy images. If a Disk Copy image is downloaded, the image volume is mounted on the desktop. Software Update looks inside of the volume for an Apple Installer Script to execute with the Installer Engine.

Destination Folder popup - if your software package consists only of a USB module, then set the Destination Folder popup to the Extensions Folder where the module will be installed. If the software package is an Installer script or a Disk Copy image, then set the destination folder to the ItemsDeletedAtBootFolder. After the installation is complete, the file will be deleted after the system is rebooted.

Language popup - set this popup to the language that the software package supports. You can provide localized versions of your software. Each software package will be matched by this popup to the country code for the target system software. If there are no software packages with a match for the country code, and if there is an International English package, then this choice is presented to the user.

Download URL Field - provide the complete URL that Software Update will use to download your software package. The software package will be maintained on your support web server. You will be responsible for ensuring that the URL remains valid. DTS recommends the use of a web server to stage your download from. An ftp server may not be easily accessed from behind a firewall if the user has not set their system for passive ftp access.

Product Requires USB Version Field - enter the version of USB required by the software package. Software Update compares the of Mac OS USB present on the system with the required version of USB. If the required version is greater than the release of USB present on the system, the software package will not be offered as a download option to the user.

If the download package is an encoded Disk Copy image, enter at least version "1.4.1" in this field. Support for Disk Copy images requires the presence of Software Update 1.1.1 which shipped as a part of Mac OS 9.0.4. While there is no way to specify the required version of Software Update required to be present, you can require USB 1.4.1 which is built into Mac OS 9.0.4. One caveat for systems with no built-in USB: the user may have installed a USB PCI or Cardbus card and have installed the USB Adapter Card software. In this case, Software Update may not be able to handle a Disk Copy image. Software Update can be used to upgrade itself to the 1.1.3 or greater release.

The "BinHexed File Name" and the "Version" fields are annotated with asterisks. These are optional fields.

There can be multiple software packages associated with a device. Each software package is presented to the user in the Software Update window. As the user clicks on each selection, the associated product description is presented to the user.


Back to top


Add Description

You can provide a description of your software package using the "Add Description" link. There will be an Add Description link for each software package that you provide. At a minimum, you should provide a description using International English:

tn1191.6.gif



Back to top

Installing USB Shims and other related software

For many software packages, there are multiple files to be installed. There are two different options for developers, one of which is dependent on the presence of Mac OS 9.0.4 or greater. For Mac OS 9.0, the only mechanism to install multiple files is to write an Apple Installer script. This option also works with later versions of the Mac OS.

With Mac OS 9.0.4, an alternative exists to support third-party installers, including those from Aladdin Systems and MindVision Software. This is possible because Software Update for Mac OS 9.0.4 supports Disk Copy images such that Software Update will detect if the download file is a Disk Copy image and mount the image file. After the volume is mounted, Software Update will look for a special Apple Installer script, which in turn launches the installer application. The installer application can install additional software, such as applications, plugging, read me files, and other files as well as the USB driver and shim file. After the installer application completes, the Apple Installer script will activate a USB shim file so that no restart is required.

Using a third-party installer

There are a couple of third-party vendors that have installer software packages which allow you to create standalone installer applications for your products. Apple is supplying these vendors with a special Apple Installer script file which you include with the installer application in a Disk Copy image file to make the USB Software Locator installation work under Mac OS 9.0.4 and later. Follow the instructions which each vendor provides to create an installer for your product. The end result will be a Disk Copy image file that will be encoded in BinHex or MacBinary format and placed on your HTTP server. The typical steps are as follows:

  1. Use the installer software to create your installer application.

  2. Follow the guidelines specified by the installer software vendor in creating the Installer document.

  3. If you have a USBShim file to install or if you experience problems with USB 1.4.2 under Mac OS 9.0.4 matching your new driver to the device, you will need to create a file of type 'TEXT' with the file name "activate.dat". The file will contain either only a single line or three lines of text. The format is as follows:
Name_of_USBShim_File<return> // file name of shim in Extension Folder on first line
VendorID<return> // the decimal value of the vendor ID on second line
ProductID<return> // the decimal value of the product ID on third line

If there is no USBShim file to be activated, a <return> character on the first line of the file will indicate this. In order for the VendorID and the ProductID to be read correctly, they must be on the second and third lines of the file, respectively. IMPORTANT NOTE: Before including the Vendor and Product ID values in the "activate.dat" file, check first that USB 1.4.2 (Mac OS 9.0.4) does not match the driver to your device. You can either omit the "activate.dat" file if there is no USBShim, or you can only specify the name of the USBShim file in the "activate.dat" file. Create your Disk Copy image and test the Software Update process. If the device does not work immediately after the download, but does if the device is disconnected and reconnected, then your device will need help. Create a new Disk Copy image file, but with an "activate.dat" file which includes the Vendor and Product IDs and retest.
  1. Place the installer application, the supplied Apple Installer script and the "activate.dat" files in a folder and create a Disk Copy image of the folder. A copy of the Apple Installer Script "SubLaunchScript" is included in the Utilities folder of the SDK.

  2. Encode the Disk Copy image into MacBinary or BinHex format. Software Update for Mac OS 9.0.4 supports both encoded formats.

  3. Place the encoded image file on the guest-accessible Web or FTP server.

  4. Use the information above to register your download package with the USB Editor Web Page.

  5. When you create a new software package entry for the first time, make sure that you set the "Move To Production" popup menu item to "N". The default setting is "Y", which means that the information on the page will be moved to the USB Production Server when the next update occurs. Do not set the popup to "Y" until you are ready for the world to be able to download your package.

  6. Use the "Software Locator Switch" application that is included in the Tools folder of the "USB Software Locator Kit", to point Software Update to the "Staging Database" rather than the "Production Database" to find USB Driver downloads. The "USB Software Locator Kit" is included as part of the Mac OS USB DDK.

  7. Make sure that you have Mac OS 9.0.4 installed and connect your device. Assuming that there is no driver in the Extensions folder to support the device, USB will prompt you to search the Internet for a driver.

  8. While testing your live update process, have USB Prober active with the Expert Log window open. Use the "Clear" key on the numeric keypad, to clear the Expert Log window of unnecessary information, then proceed with the live update. If there are problems, the log window will display information to help in understanding what went wrong.

Caveats With Using a Third-Party Installer

The following list the known issues with using a third-party installer application.

  • The installer can install complete application packages and other software; however, this download may take time. Keep in mind that the end user may only need specific drivers to support the device, like the USB Driver, shim, and required shared libraries. You can provide multiple options to the user to download a basic driver package or an entire application suite that includes the driver.

  • The Apple installer script process cannot activate an INIT on the fly like it can for a USBShim. If your installation package installs an INIT file, and the execution of the INIT is required, your software package will require a system restart. Set the "Restart machine after install:" popup menu in the Software Package download description to "Y" in this case.

  • The Apple installer script can only support a single installer application. Do not place more than one installer with the Apple installer script.

  • The third-party installers provide a progress mechanism, which is not presently used. The progress thermometer which the Installer Engine presents provides a very limited amount of progress for the execution of "action atoms". In the Apple installer script, there is only the single action atom which loads the installer. If the installer does a lengthy installation, the progress thermometer presented by the Installer Engine will not move. In a future release of the Installer Engine, there will be better communication between the two processes in providing progress information.

  • Under Mac OS 9.0.4, USB may not properly match the downloaded driver to the device. To address this problem, the Apple installer script reads the Vendor and Product IDs of the device from the "activate.dat" file to know how to find the device in the name registry and make calls to activate the device properly.

  • If you experience problems with the download, Software Update may report the message "An error occurred while downloading an update". This message results because a download problem was reported by Network Browser in downloading the file. Check whether your URL includes a guest access password for an FTP download. We strongly recommend the use of an HTTP server to download the software or the use of an anonymous-access ftp server. Another reason for not using an FTP server is that your customers may be sitting behind a firewall where a "passive" mode transfer is required. While it might be easy to explain to the user how to fix this problem, the use of an HTTP server eliminates this potential tech support call.


Back to top

Implementing an Apple Installer Script

A second option for creating a software package which installs multiple files is to create an Apple Installer script. This option requires the use of the Macintosh Programmer's Workshop build environment in order to perform the ScriptCheck process. An overview of the development process is that you create an Apple Tome consisting of archived files and resources that will be installed. Write an Apple Installer Script document and perform the ScriptCheck process. Use the MergeScriptMPWTool to merge the tome file into the installer script. Finally, encode the file in BinHex format, and load the file to your HTTP server.

For those who are familiar with writing Apple Installer scripts, a sample is provided with the Mac OS USB DDK in the USB Software Locator Kit folder. The script is built with the CodeWarrior, but must be ScriptCheck'd using MPW. The sample script includes an Action Atom code resource to activate a USBShim. The Action Atom code resource is executed after all files and resources have been installed. The use of the Action Atom code resource can be removed if there is no USBShim to activate.

For software packages that implement a USBShim, there is a new call defined in Mac OS USB 1.3.5, USBAddShimFromDisk, which will activate a USBShim on the fly. Unfortunately, this call is broken under Mac OS USB 1.3.5, but is fixed under Mac OS USB 1.4.1 and greater.

The following points must be considered if you choose to implement an Apple Installer script to install your USB software components.

  • The USBAddShimFromDisk call is used to activate the USB shim by a post-installation action atom in the Apple Installer script file.

  • Only the Apple Installer script is supported by the Software Update mechanism for Mac OS 9.0. Refer to the previous section on using third-party installers for Mac OS 9.0.4 and later.

  • In the case that the Apple Installer script is downloaded, the associated "tome" file must be merged into the script file. A tool is available in the sample code package that merges the tome file into the Installer script file.

  • The Apple Installer is not part of the download process. Software Update uses the Installer Engine, which is included in the Application Support folder, to perform the installation actions of the script.

For those unfamiliar with either the Apple Installer or a tome file, the tome file contains the compressed files and resources which will be installed by the Installer Engine. The Installer script contain a number of resources, called "atoms" that describe:

  • the rules to check whether the installation can be performed;

  • what files and resources will be installed or removed;

  • where the files and resources can be found; and

  • additional code resources to be executed in support of the installation process.

The source for the Installer script is a resource source file. Typically, the MPW Rez tool is used to build the Installer Script; however, it's also possible to use the Metrowerks CodeWarrior IDE for this purpose. An example USB module and USB shim with Installer script source and post-installation action atom source is provided in the Mac OS USB DDK.

The above describes the use of an Installer Action Atom to instantiate the USB shim. Alternatively, the action atom code could be written to perform other tasks. Refer to the Apple Installer SDK for more information on the implementation of action atoms.


Back to top

Apple Installer Script Tips

The following are some notes to help you in creating an Apple Installer script to work with Software Update:

  • The source code for an Apple Installer script is a resource script file, which can be compiled into a resource file using either MPW or Metrowerks CodeWarrior.

  • You will need to use the Macintosh Programmer's Workshop (MPW) build environment for two steps of the Installer Script build process (1) to use the ScriptCheck tool, and (2) to use the MergeScriptMPWTool to produce the single Installer Script file that Software Update knows how to implement.

  • Use the FileCrusher Tool to create a tome file, the file containing the compressed files and resources, which the Installer script will install.

  • Use the MergeScriptMPWTool to merge the tome file into the Installer Script file.


Back to top

Testing Your Live Update

Apple has set up two servers to handle the USB software locator process, a production server and a staging server. When you define or update a software package entry, you should ensure that the "Move To Production" popup menu is set to "N" until you are satisfied that the locator process works as expected. In order to have Software Update access the staging server, use the Software Locator Switch application to direct Software Update to either server for USB software.

The Software Locator Switch application is included as part of the Mac OS USB DDK. Once you are satisfied that the software is properly downloaded from the staging server, set the "Move To Production" popup menu to "Y". Within 24 hours, the changes will be picked up by the production server.

IMPORTANT NOTE: You may find during live update testing that instead of downloading the latest driver package, an older driver package is installed instead. This is a known issue with regards to how software download information is cached on the USB Editor servers. The problem occurs when a software download package is set with one "Download URL:" path, and later modified to a different path. Until this problem is addressed, you are advised that if the "Download URL:" path must be changed, delete the download package entry and create a new download package entry.


Back to top

Tips

You may find the following information useful when planning your software update:

  • We encourage you to make the download available from your web server, as opposed to using File Transfer Protocol (FTP) server. You can specify <http://www.mycompany.com/myusbdriver.hqx> for the download address as an alternative to specifying the download from an FTP server. Setting the download from an HTTP server gets around the problem of trying to access an FTP server from within a firewall.

  • If you must use an FTP server, consider supporting PASV mode. Many customers will have machines that reside within a firewall where only passive connections to FTP servers are allowed.

  • HTML files that are going to be displayed in Software Update should have the following two items.

    • A META tag such as <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=x-euc-jp">, where the charset specifies the encoding where the HTML was created.

    • The body of the HTML should be enclosed by a <FONT NAME=""> where font name specifies the font to be used to display the HTML.

    Software Update will convert the HTML from UTF-8 to the encoding specified in the META tag. If a charset is not specified, Software Update will use the default encoding for the running System. The list of Internet names for MacOS encodings is located at:

    Text Encoding Converter Documentation.

    • For example, the Internet name for Mac Roman is "x-mac-roman".


Back to top

Summary

Mac OS 9.0 and Software Update provides a new mechanism for USB developers to support their devices. Users can easily download a USB driver to support their devices if they have an Internet connection and the USB driver software is registered with the USB Editor Web Page.


Back to top

References

Apple Installer SDK

Latest Mac OS USB DDK


Back to top

Change History

01-October-1990

Originally written as Technote 1191 -- USB Software Update.

01-June-2000

Updated to reflect support for third-party installers under Mac OS9.0.4.

23-February-2001

Updated to change the name to USB Software Locator and to mention the availability of the "SubLaunchScript" in recent USB DDK's.


Back to top

Downloadables

Acrobat

Acrobat version of this Note (560K).

Download

Acrobat

Mac OS USB API Reference Guide.pdf

Download




Back to top


Technical Notes by Date | Number | Technology | Title
Developer Documentation | Technical Q&As | Development Kits | Sample Code




Gray line

Contact ADC |  ADC Site Map |  ADC Advanced Search
For information about Apple Products, please visit Apple.com.
Contact Apple | Privacy Notice
Copyright © 2002 Apple Computer, Inc. All rights reserved.
1-800-MY-APPLE