Thesycon Systemsoftware & Consulting GmbH

PnP Driver Installer

A Customizable PnP Driver Installer for Windows

Reference Manual

Version: Date: Authors:

1.8.0 13 December 2013 Gnter Hildebrandt Rene Mller

Thesycon Systemsoftware & Consulting GmbH Werner-von-Siemens-Str. 2 D-98693 Ilmenau Germany Tel: +49 3677 8462 0 Fax: +49 3677 8462 18 http://www.thesycon.de

Contents

Contents
Table of contents 1 Introduction 1.1 1.2 Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 5 5 5 7 7 7 7 8 8 8 9 9 9 12 12 12 13 14 14 14 15 15 18 20 22 24 24 26

2 Operation 2.1 Driver Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 2.1.2 2.2 2.3 2.4 Operation Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Setup Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . .

Driver Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Demo Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Silent mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 Silent Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.2 Silent Uninstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Line Parameters . . . . . . . . . . . . . . . . . . . . . . . . . Exit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.5

Signing Driver Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 Customization 3.1 3.2 3.3 Delivery package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation Files (.inf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installer Conguration (setup.ini) . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1 3.3.2 3.3.3 3.3.4 [Setup] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . [Setup_x86] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . [Setup_x64] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 Support for Different Languages 4.1 Language-Dependent License Text . . . . . . . . . . . . . . . . . . . . . . . . .

5 Limitations

PnP Driver Installer Reference Manual

1 Introduction

1 Introduction
The PnP Driver Installer can be used to install kernel mode drivers for Windows in a reliable and convenient way. It can handle the rst-time installation, driver update or removal of the driver software. The driver installer can be run with a graphical user interface or in silent mode. It can be customized to support different devices and kernel-mode drivers. Regardless of the system state, the installer makes sure that the correct driver is installed. Currently, it supports the languages English and German. Further languages can be added on request.

1.1 Supported Operating Systems

The PnP Driver Installer supports the following operating systems: Windows 2000 Windows XP (32 and 64 bit) Windows Server 2003 (32 and 64 bit) Windows Home Server Windows Vista (32 and 64 bit) Windows Server 2008 (32 and 64 bit) Windows 7 (32 and 64 bit) Windows Server 2008 R2 Windows Home Server 2011 Windows 8 (32 and 64 bit) Windows Server 2012 Windows 8.1 (32 and 64 bit) Windows Server 2012 R2

1.2 Features
The PnP Driver Installer provides the following features: Support for rst-time installation, driver update and removal of the driver software. Removes all other driver packages for the device that match the hardware IDs of the package to be installed. Installs the exact driver version included in the installed package (even in the case of a rollback). Interactive mode with graphical user interface. PnP Driver Installer Reference Manual 5

1 Introduction

Silent mode to integrate the installer into other setups. Support for different languages. Can be customized easily. Supports signed and unsigned drivers.

PnP Driver Installer Reference Manual

Operation

2 Operation
2.1 Driver Installation
2.1.1 Operation Sequence At rst, the setup application checks whether there is an existing installation on the target system. If that is the case, and if it differs from the current setup, it is uninstalled no matter whether the existing installation is older or newer. Afterwards, the setup performs a cleanup based on the information available in the driver package to install. During this cleanup all drivers that match one of the hardware IDs supported by the driver package are uninstalled, including their assignment to corresponding devices. The cleanup is important in cases where the removal of an existing installation failed for any reason or drivers have been installed in another way, e.g. by means of system tools like the device manager. In the next step the setup application performs a preinstallation of the driver software. This means that the driver will be installed on the system but not yet assigned to any device. The system assigns the driver as soon as it recognizes that the corresponding device is connected. Before the driver is assigned the system checks whether there is another matching driver that is a better choice for the device. The decision of which driver is better depends on the operating system, the driver version and signature of the driver package. Both the removal of an existing installation and the additional cleanup make sure that only the driver provided with the setup is present on the system and successfully assigned to the corresponding device, independent of the operating system and no matter whether the driver package is installed the rst time, or an update or a rollback is performed. If the setup is running with a graphical user interface it prompts the user at the end of the installation to disconnect and reconnect the device. This ensures that the driver is also assigned in the case of the user not yet connecting the device to the system or in the case of the system not being able to recognize the current connection for any reason. The user may ignore this request and can connect the device at a later point in time to complete the installation successfully. In the case of the setup being executed and detecting an existing installation that is identical, the user is informed that the installation has completed. No further installation steps will be performed. 2.1.2 System Setup Dialogs Depending on the operating system and the driver package (signed/unsigned, setup class) Windows may raise additional setup dialogs, e.g. to prompt the user to conrm installation of an unsigned driver, to trust the driver vendor or to assign the installed driver to a connected device (Found New Hardware Wizard). The PnP Driver Installer minimizes their appearance and integrates the remaining, inevitable dialogs as well as possible into its user guidance. Under Windows XP and the corresponding server systems, the Found New Hardware Wizard may appear at the end of the installation or later if the system detects a connected device. This system wizard prompts the user to assist the assignment of the preinstalled driver to the device. The user must follow the instructions of the hardware wizard, i.e., he can choose the option "No, not this time" on the rst page and should continue with "Next" on every following page until the wizard nished. Windows setup dialogs can be avoided by signing the driver package (see section 2.5).

PnP Driver Installer Reference Manual

2 Operation

2.2 Driver Uninstallation

During every installation, the uninstallation support is installed as the very rst step, so that if the installation fails for any reason (see section 2.4.1) the uninstallation can be performed to cleanup the system. The uninstallation is supported in the following ways: 1. If an installation is performed and the setup detects an existing installation on the target system that differs from the current one, the uninstaller of the existing installation is executed before the new installation starts (see section 2.1.1). This means it is not required to explicitly cleanup the system before an installation. This is done implicitly by the installer. 2. Unless specied otherwise, the installer creates an entry in the programs control panel of the system, which is the Programs and Features control panel on Windows Vista and later and the Add or Remove Programs control panel before Windows Vista. The user may run the driver uninstallation by means of this control panel. In this case the uninstaller shows a graphical user interface. You can prevent the installer from creating an entry in the control panel by means of the appropriate command line parameter (see section 2.4.1). This may be useful if you provide an enclosing setup and you dont want to allow the user to uninstall the driver package separately. 3. The setup allows you to perform an explicit silent uninstallation. Enclosing setups, such as application setups, are especially addressed by this feature. Usually the uninstallation of an enclosing setup should also involve the uninstallation of the driver package. The driver setup provides the appropriate command line parameters (see section 2.4.2). Note that it is not required to use the same version of the setup executable that installed the existing driver package, but it must be a setup executable of the same product that is dened by the setup.ini. The called setup executable may be located anywhere on the system but the corresponding setup.ini le must be located in the same folder. The caller of the uninstallation is responsible for the deletion of the setup executable le, if required, because the application doesnt delete itself when uninstallation is nished. Note: You should always wait for the result of the uninstallation! The uninstallation may be aborted for reasons that require some user interaction (see section 2.4.2). Furthermore, any following installation will be aborted as long as an uninstallation is running. Even if your enclosing setup application does not intend to run an installation immediately after, the user may do so.

2.3 Demo Version

The demo version of the PnP Driver Installer is free and has no limitations except that it requires a run of the Demo Mode Control Panel DemoModeCpl.exe concurrently. The panel must be started before the setup can be used. It requests the user to enter a random number and to enable the Demo mode by clicking the button Enable. The Demo Mode Control Panel is always displayed on top of the desktop. It must run until the (un-)installation is nished.

2.4 Silent mode

The PnP Driver Installer supports a silent mode that can be enabled with command line options. This mode is designed to integrate the PnP Driver Installer into a surrounding setup program. 8 PnP Driver Installer Reference Manual

Operation

When using this mode the following facts have to be considered: The silent mode only suppresses the graphical user interface of the setup application. It does not suppress any Windows setup dialog that may appear. Windows setup dialogs can be suppressed by signing the driver package (see section 2.5). The setup is not a console mode application, even when running in silent mode. This means when executed on the command line the command prompt returns immediately while the setup is still running. To get the setups exit code it should be started by an application that is able to wait for another process. The caller of the setup is responsible for user guidance which depends on the exit code (see sections 2.4.1 and 2.4.2). As described in section 2.1.1 the installation is not complete until the system detects a connected device and assigns the preinstalled driver. To ensure that the driver is also assigned in the case of the user not yet connecting the device to the system or in the case of the system not being able to recognize the current connection for any reason, the caller of the setup should prompt the user at the end of the installation to disconnect and reconnect the device as the PnP Driver Installer does when running with graphical user interface. 2.4.1 Silent Installation Command Line Parameters Parameter /S /DIR="target path" /NOPCPL Description Run installer in silent mode. Installation directory on the target system. If not specied, the default installation directory given by the setup.ini le is used. Prevent the installer from installing uninstallation support in the programs control panel of the system, which is the Programs and Features control panel on Windows Vista and newer operating systems and the Add or Remove Programs control panel before Windows Vista respectively.

Example: setup.exe /S /DIR="c:\MyCompany\MyProduct" Exit Codes Status Code 0 Description The setup nished successfully. Recommended Action -

PnP Driver Installer Reference Manual

2 Operation

100

Setup aborted: Another PnP installation process is currently running on the system.

101

102

103

Setup nished successfully, but to complete driver installation a restart is required. Setup aborted: The current operating system is not supported by the setup. Setup aborted: Unexpected error.

Inform the user to close all open hardware installation wizards. If no wizard is currently open the system is probably performing some installation steps in the background. Wait some time and run setup again. Reboot the system. If the device is already connected, no disconnect/reconnect is required after reboot. Inform the user and abort.

104

109 111 112

113

114

115

118 123 125

Setup aborted: The current user has no administrator privileges which are required to proceed. Setup aborted: Invalid command line parameters. Setup aborted: Another installer / uninstaller is already running. Setup aborted: The installation directory could not be created on the destination system. Setup aborted: The uninstaller le could not be extracted to the installation directory. Setup aborted: Not all required les could be installed (Probably one or more les already exist in the installation directory and could not be overwritten.). Setup aborted: Any driver could not be preinstalled on the system. The most likely reason is that the user didnt accepted installation of unsigned drivers. Setup aborted: Self-registration of some modules failed. Setup aborted: setup.ini is not present or is corrupt. Setup interrupted: Installation cannot continue because of some locked resources. A restart is required.

Inform the user and abort. The setup creates a log le in the users temp directory. This le may help to analyze the problem. Inform the user and abort.

Call the setup with correct command line parameters. The user must nish the running (un-) installation at rst. Inform the user or choose another installation directory and run setup again. Inform the user or choose another installation directory and run setup again. Inform the user or choose another installation directory and run setup again.

Inform the user that he should accept installation of unsigned drivers despite the system warnings and run setup again.

Inform the user and abort. Provide a correct setup.ini le. Reboot the system and run installation again.

10

PnP Driver Installer Reference Manual

Operation

126

Setup aborted: Running this version of the setup application requires activation of the Demo Mode by means of the corresponding "Demo Mode Control Panel".

This code is only returned in the demo edition of the setup, which is not delivered to the end user. It has not to be handled by a calling application. If the setup is executed in non-silent mode the information is displayed by a message box. Otherwise only an error entry is written to the log le of the setup in the users temp directory.

PnP Driver Installer Reference Manual

11

2 Operation

2.4.2 Silent Uninstallation Command Line Parameters Parameter /SU Description The setup silently uninstalls the currently installed version, if there is any.

Example: setup.exe /SU Exit Codes Status Code 0 Description The uninstallation nished successfully. "Successfully" means that the uninstallation is as complete as possible. The uninstaller may detect that the existing installation is corrupt (e.g., because the user deleted some installed les). This may prevent the uninstaller from performing all required steps or may even prevent the whole uninstallation in the worst case. Since neither the user nor any calling application can resolve such problems no error code is returned. Uninstallation aborted: Another PnP installation process is currently running on the system. Solution -

100

101

102

103

Uninstallation nished successfully, but a restart is required for completion. Uninstallation aborted: The current operating system is not supported by the uninstaller. Uninstallation aborted: Unexpected error.

Inform the user to close all open hardware installation wizards. If currently no wizard is open the system is probably performing some installation steps in the background. Wait some time and run setup again. Reboot the system.

Inform the user and abort.

104

Uninstallation aborted: The current user has no administrator privileges, which are required to proceed.

Inform the user and abort. The uninstaller creates a log le in the users temp directory. This le may help to analyze the problem. Inform the user and abort.

12

PnP Driver Installer Reference Manual

Operation

109 111

123 126

Uninstallation aborted: Invalid command line parameters. Uninstallation aborted: Another installer / uninstaller is already running. Uninstallation aborted: setup.ini is not present or is corrupt. Uninstallation aborted: Running this version of the setup application requires activation of the Demo Mode by means of the corresponding "Demo Mode Control Panel".

Call the uninstaller with correct command line parameters. The user has to nish the running (un-) installation at rst. Provide a correct setup.ini le. This code is only returned in the demo edition of the setup, which is not delivered to the end user. It is not to be handled by a calling application. If the setup is executed in non-silent mode the information is displayed by a message box. Otherwise only an error entry is written to the log le of the setup in the users temp directory.

2.5 Signing Driver Packages

A driver package consists of driver les (.sys), installation les (.inf) and further optional les (e.g. DLLs). To sign a driver package, a catalog le (.cat) is created in the rst step. This catalog le contains a hash value of each le belonging to the driver package. In the next step, the catalog le is signed by means of a certicate. Either the signature is obtained from a WHQL submission (i.e. a submission to the Windows Hardware Quality Labs program of Microsoft) or by means of a vendor certicate (Authenticode). A WHQL submission is a more expensive and timeconsuming process while a vendor signature can be created within seconds after you achieved a valid certicate from a certicate authority (CA). For further information please contact Thesycon. Note: Vendor signatures do not have any noteworthy impact on driver installations before Windows Vista. To enjoy the advantages of a signed driver package on Windows 2000, XP and corresponding server systems, a WHQL signature must instead be used. A signature may be required for the following reason: Windows setup dialogs can be suppressed, i.e. it is possible to install a driver completely silent (with administrator privileges). Windows Vista 64-bit and later 64-bit operating systems require signed driver packages (or at least signed driver les). Otherwise the drivers can be installed but are never loaded by the system. Windows provides built-in drivers that may be compatible in some cases with the device to install (see section 5). Built-in drivers are always WHQL signed. Windows always prefer signed drivers when selecting the appropriate driver for a device. To solve this, the driver package should be signed. Note: Before Windows 7 WHQL signed drivers are preferred over vendor-signed drivers according to the default system settings.

PnP Driver Installer Reference Manual

13

3 Customization

3 Customization
3.1 Delivery package
The PnP Driver Installer consists of the setup application, setup.exe, and the corresponding conguration le, setup.ini. To create the package to be delivered to the end user, the PnP Driver Installer must be customized. That means, depending on the task of the installer, the conguration le setup.ini must be adapted. Furthermore, the installer must be completed with the required driver les and optional helper les that adapt the behavior of the setup. The setup application itself should never be modied. The les that complete the setup are: Required One or more driver les (.sys) for 32-bit and/or 64-bit systems. One or more installation les (.inf) for 32-bit and/or 64-bit systems. One or more signed catalog les (.cat) for 32-bit and/or 64-bit systems. Catalog les are optional for some older operating systems such as Windows XP. Even on 32-bit Windows versions as well as Windows Vista (64-bit) and Windows 7 (64-bit) it is possible to omit them as long as the driver les (.sys) are signed, but this is not recommended. Catalog les for each driver package are expected by Windows and signicantly improve the user experience during installation. On Windows 8 (64-bit) and newer 64-bit Windows versions driver packages without signed catalog les will not work. Optional One or more COM DLLs to be registered for 32-bit and/or 64-bit systems. The license text. The le that contains the public (!) key of the vendor certicate used to sign the driver package. The vendor-specic bitmap le that will be displayed by most setup wizard pages. Additional les that extend the driver package or the installation in general. All les, together with the setup.exe and the setup.ini, should be stored in the same folder. Optionally sub-folders can be used to separate les specic for 32-bit and 64-bit operating systems respectively.

3.2 Installation Files (.inf)

An installation le describes how a kernel driver is installed. It contains one or more copy le sections that control how specic les of the driver package are copied to the target system. These sections can contain one or more lines such as: <driver_name>.sys,,,0x00000004 14 PnP Driver Installer Reference Manual

Customization

The ag 0x00000004 means COPYFLG_NOVERSIONCHECK. If this ag is set, the installation can overwrite a newer version of the le without showing a warning box to the user. This is especially useful in the case of a rollback. It is strongly recommended to set this ag for all les in the copy section.

3.3 Installer Conguration (setup.ini)

The setup.ini le is a text-based conguration le. It can be edited with a text editor such as Notepad. The le is divided into sections. A section is marked by []. Do not change the names of the sections. Each section denes a set of parameters. Each parameter has a name and a value. Do not modify the names. Change the parameter values according to your requirements. 3.3.1 [Setup] This section contains general parameters that are used for both 32-bit and 64-bit systems. CompanyName Your company name shown in the programs control panel of the system, which is the Programs and Features control panel on Windows Vista and later and the Add or Remove Programs control panel before Windows Vista. Example: CompanyName=My Company ProductName The name of your product shown in the graphical user interface of the setup application and the programs control panel of the system. Note: The application automatically appends strings like Setup and Uninstall depending on the purpose of the dialogs. So dont use these strings as part of the name! Example: ProductName=My Product ProductVersion The version string of your product shown in the graphical user interface of the setup application and the programs control panel of the system. Example: ProductVersion=1.6.0.0 SetupRegPath The path to the Registry key used to store setup information. The path is relative to HKEY_LOCAL_MACHINE\Software. The key should only be used by the driver setup, because it is completely removed during implicit or explicit uninstallation. E.g., if an enclosing setup installs additional software and uses the registry key

PnP Driver Installer Reference Manual

15

3 Customization

HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct the driver setup cannot use the same key. Instead it should use a subkey like HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\DriverSetup. During uninstallation the key DriverSetup is removed. Parent keys like MyProduct etc. are only removed if they are empty. Note: This parameter must not be changed in future releases of your setup package. Otherwise the setup cannot detect whether or not another version already exists on the target system and cannot uninstall the existing version before the current package will be installed. Note furthermore that this path must be unique world-wide. To achieve this, use your company name and your product name in the path. Example: SetupRegPath=MyCompany\MyProduct\DriverSetup DefaultDestDir The default destination directory on the target system. The path is relative to Program Files. Note: The path must be unique world-wide. To achieve this, use your company name and your product name in the path. Example: DefaultDestDir=MyCompany\MyProduct ShowLicenseText Dene whether or not a license agreement should be displayed and accepted by the user before installation begins. The corresponding license text le can be provided for each language supported by the setup, e.g. license_english.txt and license_german.txt. If no languagespecic license le is available the setup always uses the default license text le license_english.txt, which is therefore mandatory as long as the license agreement is enabled. For further information please refer to section 4. The value of ShowLicenseText is either 0 (disabled) or 1 (enabled). The license agreement is optional. Example: ShowLicenseText=0 UseCustomizedBitmap Dene whether or not a customized bitmap should be displayed by the setup. The value is either 0 or 1. If set to 0, the setup displays a default bitmap. If set to 1, the setup is requested to display a customized bitmap. The name of the bitmap le must be "setup.bmp". The le is expected in the same folder as the setup application. The dimensions of the bitmap should be 164 x 314 pixels (width x height). Example: UseCustomizedBitmap=1

16

PnP Driver Installer Reference Manual

Customization

CerticateFile Name of the le containing the public (!) key of the vendor certicate that has been used to sign the driver package. To create the le just export the vendor certicate from the certicate store. Choose the export format DER encoded binary X.509 (.CER). Do not export the private key! The installer uses this le only to suppress system setup dialogs that will ask the user whether or not to trust the driver publisher. For this purpose the certicate is temporarily installed in the Trusted Publisher store. After installation has completed the certicate is not required anymore and will be removed from the certicate store. This feature is especially useful when running the setup in silent mode. Note: It is rare that the root certicate belonging to the vendor certicate is not yet present on the target system. In this case, it is automatically loaded in the background from a Microsoft server. Unfortunately this doesnt always happen during installation on Windows Vista. So the system may warn the user not to install an unsigned driver from an unknown vendor even though the driver is signed and the vendor certicate is installed in the certicate store. The installation will succeed and the driver will be loaded anyway, but because of the system warning the user may decide to abort the installation. For this reason the installer explicitly requests the system to load the corresponding root certicate if required. Note that this requires a connection to the internet. Administrators that dont allow an online connection of their target systems can download specic root certicate packages from a dedicated Microsoft server (e.g. http://catalog.update.microsoft.com). For further information please search the internet for root update or KB931125. The value is optional but because of the reasons given above it is highly recommended. Note: This parameter is ignored for operating systems before Windows Vista. Example: CerticateFile=MyCerticate.cer CopyFiles Common les to be copied to the destination directory (e.g. ReadMe.txt). Several les may be specied as a comma separated list of le names without a path. The les must be located in the same directory like the setup application. The value is optional. Note that les specied by other parameters of this section are implicitly copied and should not be specied by this parameter. Example: CopyFiles=ReadMe.txt, RevisionHistory.txt ShortCut[1..n] Optional parameters of type ShortCutX=ValueString that dene the shortcuts to be created. Start with X=1 and increment X with each shortcut denition. ValueString has the following format: SC_ROOT|SC_PATH|SC_NAME|TARGET|PARAMS|START_PATH PnP Driver Installer Reference Manual 17

3 Customization

SC_ROOT

Root directory of the shortcut. This directory will not be deleted during uninstallation. It can be set to the following variables: $SM_PROG_CURRENT_USER (start menu\programs of the current user) $SM_STARTUP_CURRENT_USER (start menu\startup of the current user) $SM_PROG_ALL_USERS (start menu\programs of all users) $SM_STARTUP_ALL_USERS (start menu\startup of all users) Optional path of the shortcut to be created. This path is relative to SC_ROOT. Name of the shortcut to be created. Full path and name of the executable le on the target system the shortcut points to. One of the variables $INSTDIR (main installation directory), $WINDIR (Windows directory) or $SYSDIR (system32 directory) should be used to reference the target le. Optional parameters passed to the target executable le when it is launched. Optional start directory for the target executable le.

SC_PATH SC_NAME TARGET

PARAMS START_PATH Example:

ShortCut1=$SM_PROG_ALL_USERS|MySubDir|Manual.lnk|$INSTDIR\RefMan.pdf|| ShortCut2=$SM_PROG_ALL_USERS|MySubDir|ReadMe.lnk|$INSTDIR\ReadMe.txt||

3.3.2 [Setup_x86] Settings in this section will only be applied to 32-bit operating systems. SupportedOS 32-bit operating systems supported by the setup. The parameter species a comma-separated list that may contain the following tokens: 2000, XP, Server2003, HomeServer, Vista, Server2008, 7, 8, 8.1, Newer The token Newer means any 32-bit operating system newer than Windows 8.1. If the list is empty, no 32-bit operating system is supported. Example: SupportedOS=XP, 7, 8, 8.1, Newer CopyFiles This parameter species the les of the setup package to be copied to the destination directory (e.g. .sys and .cat les). Several les may be specied as a comma separated list of le names without a path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The value is optional.

18

PnP Driver Installer Reference Manual

Customization

Note that les specied by other parameters of this section are implicitly copied and should not be specied by this parameter. Example: CopyFiles=MyDriver.sys, MyDriver.cat PnPDriverInf This parameter species the .inf les that describe the PlugnPlay drivers to be installed. Several les may be specied as a comma separated list of le names without path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. Note: If multiple .inf les are specied they must not be related in a bus driver architecture (see section 5). Example: PnPDriverInf=MyDriver.inf RegisterFiles COM DLLs to register. The DLLs have to support self-registration. Several les may be specied as a comma separated list of le names without path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The value is optional. Example: RegisterFiles=MyComModule.dll SubDir Sub-folder of all les listed in the section [Setup_x86]. If the parameter is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The folder will also be created on the destination system. The value is optional. Example: Location of the setup application: y:\install Installation directory: c:\Program Files\Company\Product a) SubDir=x86 The les will be copied from y:\install\x86 to c:\Program Files\Company\Product\x86. b) SubDir= The les will be copied from y:\install to c:\Program Files\Company\Product.

PnP Driver Installer Reference Manual

19

3 Customization

ShortCut[1..n] Optional parameter of type ShortCutX=ValueString that denes shortcuts to be created. Start with X=1 and increment X with each shortcut denition. ValueString has the following format: SC_ROOT|SC_PATH|SC_NAME|TARGET|PARAMS|START_PATH SC_ROOT Root directory of the shortcut. This directory will not be deleted during uninstallation. It can be set to the following variables: $SM_PROG_CURRENT_USER (start menu\programs of the current user) $SM_STARTUP_CURRENT_USER (start menu\startup of the current user) $SM_PROG_ALL_USERS (start menu\programs of all users) $SM_STARTUP_ALL_USERS (start menu\startup of all users) Optional path of the shortcut to be created. This path is relative to SC_ROOT. Name of the shortcut to be created. Full path and name of the executable le on the target system the shortcut points to. One of the variables $INSTDIR (main installation directory), $WINDIR (Windows directory) or $SYSDIR (system32 directory) should be used to reference the target le. If the parameter SubDir of this section denes a sub-folder it has to be specied too. Optional parameters passed to the target executable le when it is launched. Optional start directory for the target executable le.

SC_PATH SC_NAME TARGET

PARAMS START_PATH Example:

ShortCut1=$SM_STARTUP_ALL_USERS||My CPL.lnk|$INSTDIR\MyCpl.exe|-s|

3.3.3 [Setup_x64] Settings in this section will only be applied to 64-bit operating systems. SupportedOS 64-bit operating systems supported by the setup. The parameter species a comma separated list that may contain the following tokens: XP, Server2003, Vista, Server2008, 7, Server2008R2, HomeServer2011, 8, Server2012, 8.1, Server2012R2, Newer The token Newer means any 64-bit operating system newer than Windows Server 2012 R2. If the list is empty no 64-bit operating system is supported. Example: SupportedOS=7, Server2008R2, 8, 8.1, Newer

20

PnP Driver Installer Reference Manual

Customization

CopyFiles This parameter species the les of the setup package to be copied to the destination directory (e.g. .sys and .cat les). Several les may be specied as a comma separated list of le names without a path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The value is optional. Note that les specied by other parameters of this section are implicitly copied and should not be specied by this parameter. Example: CopyFiles=MyDriver_x64.sys, MyDriver_x64.cat PnPDriverInf This parameter species the .inf les that describe the PlugnPlay drivers to be installed. Several les may be specied as a comma separated list of le names without a path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. Note: If multiple .inf les are specied they must not be related in a bus driver architecture (see section 5). Example: PnPDriverInf=MyDriver_x64.inf RegisterFiles COM DLLs to register. The DLLs have to support self-registration. Several les may be specied as a comma separated list of le names without a path. If the parameter SubDir of this section is empty the les must be located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The value is optional. Example: RegisterFiles=MyComModule.dll, MyComModule_x64.dll SubDir Sub-folder of all les listed in the section [Setup_x64]. If the parameter is empty the les must located in the same directory like the setup application, otherwise they must be located in the given sub-folder. The folder will also be created on the destination system. The value is optional. Example: Location of the setup application: y:\install Installation directory: c:\Program Files\Company\Product a) SubDir=x64 The les will be copied from y:\install\x64 to c:\Program Files\Company\Product\x64.

PnP Driver Installer Reference Manual

21

3 Customization

b) SubDir= The les will be copied from y:\install to c:\Program Files\Company\Product. ShortCut[1..n] Optional parameter of type ShortCutX=ValueString that dene shortcuts to be created. Start with X=1 and increment X with each shortcut denition. ValueString has the following format: SC_ROOT|SC_PATH|SC_NAME|TARGET|PARAMS|START_PATH SC_ROOT Root directory of the shortcut. This directory will not be deleted during uninstallation. It can be set to the following variables: $SM_PROG_CURRENT_USER (start menu\programs of the current user) $SM_STARTUP_CURRENT_USER (start menu\startup of the current user) $SM_PROG_ALL_USERS (start menu\programs of all users) $SM_STARTUP_ALL_USERS (start menu\startup of all users) Optional path of the shortcut to be created. This path is relative to SC_ROOT. Name of the shortcut to be created. Full path and name of the executable le on the target system the shortcut points to. One of the variables $INSTDIR (main installation directory), $WINDIR (Windows directory) or $SYSDIR (system32 directory) should be used to reference the target le. If the parameter SubDir of this section denes a sub-folder it has to be specied too. Optional parameters passed to the target executable le when it is launched. Optional start directory for the target executable le.

SC_PATH SC_NAME TARGET

PARAMS START_PATH Example:

ShortCut1=$SM_STARTUP_ALL_USERS||My CPL.lnk|$INSTDIR\x64\MyCpl_x64.exe|-s|

3.3.4 Examples The SDK of the PnP Driver Installer provides example conguration les for the demo and full versions respectively of the following Thesycon drivers: USB CDC/ACM class driver for Windows USB CDC/ECM class driver for Windows USB CDC/NCM class driver for Windows USBIO for Windows

22

PnP Driver Installer Reference Manual

Customization

To get the examples working, the following steps are required (for test purposes only!): Copy the setup application (setup.exe or setup_demo.exe) to an arbitrary test folder. Copy the conguration le setup.ini from the example of interest to the same folder. Get all les listed in the setup.ini le from the corresponding SDK of the Thesycon driver and copy them to the same folder like the setup.exe. Note: If you dont have catalog les (.cat) when testing use the driver les (.sys) signed by Thesycon. This ensures that the drivers will also be loaded when the installation is performed on 64-bit operating systems. Starting with Windows 8 catalog les are mandatory on 64-bit Windows. Driver packages without catalog les are rejected by the operating system and the setup will fail. The SDK of the USBIO driver also provides COM objects that will be registered by the setup. Please refer to the USBIO documentation how to customize USBIO COM objects and how to create the required type libraries (.tlb). Registration of the COM objects is optional. It you want to skip the registration remove the listed COM DLLs and .tlb les in the setup.ini le. Adapt the hardware IDs of the driver installation les (.inf) to match the device to install. Note: If catalog les will be provided this step has to be done before the catalog les will be created and signed. Copy the created package to the destination system and run the setup application. Note: The examples are only intended for demonstration. Following the few steps described above you can check the basic functionality of the PnP Driver Installer. To get an impression of the optimized user guidance of the installer or of its silent mode, signed catalog les are required. If the catalog les are vendor-signed (see section 2.5) the public (!) key of the vendor certicate is also required (see parameter CertificateFile of the setup.ini le). Packages created with the example conguration les are not ready to be delivered to the end user! Please refer to the documentation of the corresponding driver SDK for further details about the steps required for a complete driver customization. The SDK of the PnP Driver Installer also provides a common example conguration le for an arbitrary product of an arbitrary company. The le is located in the same directory like the setup application.

PnP Driver Installer Reference Manual

23

4 Support for Different Languages

4 Support for Different Languages

By default the setup is provided with an English and German user interface. On request, additional languages can be added. In this case, you will receive the English text and corresponding instructions for translation. You will get a purpose-built setup application, once they have been integrated. Please contact Thesycon for further information. The PnP Driver Installer checks the display language of the operating system when starting. If the detected language is supported, the corresponding user interface is shown, otherwise the English user interface is displayed. On Windows Vista and later, new display languages can be added to the system by downloading the appropriate language packs via Windows Update, so the language support of the setup can be tested by changing the display language in the Region and Language control panel of the system. However, note that the setup examines the display language only to choose its corresponding user interface. To display the user interface correctly, the systems language for non-Unicode programs must also be set to the same language, as the setup is currently only provided as a non-Unicode application.

4.1 Language-Dependent License Text

When the setup supports different languages, it may also be indicated to show language-dependent license agreements. The parameter ShowLicenseText of the setup.ini le (see section 3.3) denes whether or not a license page should be displayed. If enabled, the license text les are expected in the folder of the setup executable. The default license le is license_english.txt. Its content is shown together with the English user interface and all other user interfaces for which no specic license le is provided. I.e., when the parameter ShowLicenseText is enabled the le license_english.txt is mandatory, all other license les are optional. Since license les will not be integrated into the setup application, they can be added to the setup package at any later point in time, but the PnP Driver Installer must support the corresponding language. A license text le must be created with a specic format, because the setup is a non-Unicode application. The following steps are recommended when creating such a le for a specic language: 1. Create a ReadMe le for your translator that contains the following instructions: Open a new .txt le with notepad. Enable Word Wrap in the notepad menu -> Format. Insert the translated license text. Note: Do not insert any line breaks except for new sections! Select the notepad menu item File -> Save As. In the appearing dialog choose a le name that corresponds to the desired language, e.g. french.txt. Choose the encoding option UNICODE in the same dialog. Click Save and close the le.

24

PnP Driver Installer Reference Manual

4 Support for Different Languages

2. Send the ReadMe le and the license text to the translator. 3. When you received the translated text open the Regional and Language control panel of the system and select the corresponding language for non-Unicode programs. 4. Apply and restart the system. 5. Open the translation with notepad. 6. Select the notepad menu item File -> Save As. 7. In the appearing dialog choose the le name expected by the setup application, e.g. license_french.txt. 8. Choose the encoding option ANSI in the same dialog. 9. Click Save. 10. Restore the Regional and Language settings of the system, if required.

PnP Driver Installer Reference Manual

25

5 Limitations

5 Limitations
The PnP Driver Installer is suitable for installation of most driver packages. It cannot be used in the following cases: The driver packages contains drivers forming a bus driver architecture. This is the case if the driver package contains a driver that creates child devices when loaded and if the driver package also contains drivers for these created child devices. Note that installation of driver packages containing multiple .inf les (drivers), which are not forming a bus driver architecture, is supported by the PnP Driver Installer. The system contains built-in drivers that will be installed for devices that match specic conditions. These drivers are always WHQL-signed. Built-in drivers are never uninstalled by the PnP Driver Installer, so after cleanup and preinstallation of the vendor driver there may be more than one matching driver preinstalled on the system. If the device is connected, the system will assign the best matching driver to the device. Unfortunately, it does prefer signed drivers. Additionally, operating systems previous to Windows 7 prefer WHQL-signed drivers over vendor-signed drivers according to the default system settings, so the driver provided with the PnP Driver Installer may be preinstalled on the system, but will not be loaded for the device. If it is not possible to provide the driver package with an appropriate signature, the PnP Driver Installer is not suitable in this case. Note: If these limitations prevent the usage of the PnP Driver Installer, a specic driver installer can solve this problem. Please contact Thesycon for further information.

26

PnP Driver Installer Reference Manual