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:
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.
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
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:
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.
Registering With DTS
The Software Update process begins by contacting Worldwide Developer Technical Support and submitting:
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.
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:
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.
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:
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.
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:
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
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
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.
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:
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:
Caveats With Using a Third-Party Installer
The following list the known issues with using a third-party installer application.
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,
The following points must be considered if you choose to implement an Apple Installer script to install your USB software components.
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 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.
Apple Installer Script Tips
The following are some notes to help you in creating an Apple Installer script to work with Software Update:
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.
You may find the following information useful when planning your software update:
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.
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.