Load a Driver

The following procedures describe how to load a driver into the control system test program. The procedures vary depending on whether the V1 (RAD Framework) or V2 (Entity Model) SDK frameworks are used.

Load a V1 (RAD Framework) Driver

The following procedures describe how to load a V1 (RAD Framework) driver to the control system and SIMPL program.

Locate the Correct Driver File

1. Navigate to the Crestron Driver Portal in a web browser.

2. Search for the driver that matches the device model and download it to the local computer. If no match is found, it is possible that a compatible driver exists for other models in the same series that uses the same API.

NOTE: If contacting Crestron True Blue Support for assistance about a driver, ensure that the full model number is provided whenever possible so that Support can determine the correct year, series, and model for the associated device. Support is unable to assist with driver issues that are reported for incomplete model numbers. As an example, refer to the following image for a breakdown of model numbers for various Samsung® display models.

Confirm Version Compatibility

Ensure control system series, firmware, and software versions are compatible with the desired driver. Use the download pages and help files in the Crestron Driver Portal to locate the supported platform and SDK version used to develop the driver. Release dates listed on the Crestron FTP Server can also help to identify corresponding software and firmware versions. Refer to Knowledge Article 1001110 for more information on the Crestron FTP server.

For example, to determine the compatibility of a Samsung® Neo QLED driver (ID 5938) released in April 2025:

• Locate its page in the Crestron Driver Portal to determine it was developed for 4-Series control systems with Crestron Drivers SDK version 14.

• Use the SDK Framework Comparison Matrices to determine that SDK version 14 requires a minimum Crestron Database version 212.00.002.00 (released May 2022).

• Reference the driver help file to determine that the driver was tested with Crestron Database version 228.05.002.00 (released January 2025).

• Use the Crestron Database 228.05.002.00 release date to determine that SIMPL version 4.3000 (or later) and 4-Series firmware version 2.8005.00012 (or later) are required to use this driver.

Load the Driver File to the Control System

Unlike SIMPL and SIMPL+ module files (.umc, .usp, and .ush extensions), driver package files (.pkg) are not imported into SIMPL. The .pkg file must be uploaded to a control system using the Crestron Toolbox™ software File Manager or SFTP. The driver file location is then referenced by the wrapper module in SIMPL programming (as described in Add Driver Modules to the SIMPL Program and Specify the Driver File Location).

Note the following when loading the driver:

• Do not change the .pkg file name.

• The file location on the control system is arbitrary, but it is recommended to load the .pkg file to the \user\ directory, as this location is reserved primarily for drivers, configuration files (XML, JSON, and so forth), and other files utilized by programs. This location also helps to simplify the string sent to the <DriverFile> input on the wrapper module.

• Optionally, logically-named subfolders can be created to help with organizing driver package files. However, in these cases, the full string of the .pkg file location on the control system must be sent to the <DriverFile> input on the wrapper module.

• File paths are case sensitive on 4-Series® control systems. However, file paths are not case sensitive on 3-Series® control systems.

Wrapper modules may automatically create a \CrestronCertifiedDrivers\ subfolder to extract .pkg file contents as shown in the image below.

Add Driver Modules to the SIMPL Program

SIMPL v4.3000 (or later) and Crestron Database v227.00.003.00 (or later) include Crestron Device Drivers wrapper modules.

Crestron Driver modules can be accessed in SIMPL by navigating to Program View > Symbol Library > Crestron Modules (CresDB XX.XX.XX.XX) > Crestron Certified Drivers. Right-click on the folder and then select Find to search for specific modules.

Ensure the latest versions of the Crestron Drivers modules are selected when adding them to the Logic folder. Press F1 on the keyboard to open the help files for Crestron Drivers modules.

Specify the Driver File Location

The file location of the driver on the control system must be sent to the module using the <DriverFile> input string before pulsing <LoadDriver>.

• Using the example driver referenced in Load the Driver File to the Control System, the string specified (in MSEND, SIO, and so forth) driving <DriverFile> would send FlatPanelDisplay_LG_65SK9500-SmartTV_IP.pkg.

• The same driver .pkg file can be referenced by multiple module instances. However, the module initialization must be performed sequentially and not simultaneously. Use <DriverLoaded> or <Connection_F> feedback to drive a delay (+/- 2 seconds) for initialization of the next Crestron Driver module instance.

Load the Driver File with the Module

After the driver file path <DriverFile> has been specified, some drivers may require additional input before pulsing <LoadDriver>:

• When <LoadDriver> is pulsed, the module will find the <DriverFile>, extract and read its contents, and then determine whether all of the driver's required inputs have been specified.

• If experiencing issues loading the driver, latch the <EnableLogging> signal high first and observe messages on <Log> in SIMPL Debugger when <LoadDriver> is pulsed.

  In the example SIMPL image shown in Review and Drive UserAttributes, the driver's <Log> feedback indicates that <IP_Address> was required before pulsing <LoadDriver> for <DriverLoaded> to go high.

Review and Drive UserAttributes

Some drivers may require UserAttribute values to be inputted before attempting a <Connect>. UserAttributes may include require input values such as MACADDR (for Wake-on-LAN devices) or instructions for how to configure device settings to enable control. Note the following:

• UserAttributes are unique to each driver, so they must be reviewed before driving input signals. For example, it cannot be assumed that UserAttribute1 will always be used to provide MACADDR.

• Driver information can be inspected in a text editing software prior to loading and testing in SIMPL. To do so, extract and unzip the driver (by renaming the extension ".zip" from ".pkg"), and ensure the Hide Extensions for Known File Types setting is deselected in File Explorer Options (for Windows OS). Then, inpsect the .dat or .dll file in text editor tool.

NOTE: The Notepad++ JSTool plugin can be used to make JSON contents more readable. This plugin allows a programmer to find information about supported models, required programming or user input, setup instructions for third-party devices, device capabilities, and so forth without needing to inspect feedback signals in SIMPL Debugger. Refer to the image below.

• 

• Additionally, Crestron Driver files can be opened in a text editing software for information on device setup and control.

  • Inspect the UserAttributes section for when and how to drive the required signals.

  • In the example below, the driver indicates that the UserAttribute1 string is used to pass in the display's MACADDR and that it must be sent before attempting a connection. UserAttribute2 and UserAttribute3 provide instructions for how to configure the device for control (their corresponding inputs do not need to be driven with any values).

  

• Alternatively, a programmer can define the UserAttribute feedback signals on the Crestron Drivers module. The feedback signals will populate with information from the driver after <DriverLoaded> feedback goes high.

  • Use SIMPL Debugger to view the feedback signals and determine what should be sent into each UserAttribute input. Feedback signals include IsAvailable, Label, Description, Type, DataType, IsPersistent, and RequiredForConnection. Refer to the help file for the driver module (F1) for more information.

  • After the UserAttribute input signal has been driven and <DriverLoaded> feedback is high, pulse the corresponding <UserAttribute#SendItIn> signal.

The following image shows an example of the logic used to drive the required inputs on a driver wrapper module.

Load a V2 (Entity Model) Driver

The following procedures describe how to load a V2 (Entity Model) driver to the control system and SIMPL program. Two different methods may be used: configuring device drivers online with the Crestron Device Driver Configuration Tool, and configuring device drivers offline.

Crestron Device Driver Configuration Tool

The Crestron Device Driver Configuration Tool consists of a web server and pages that allow programmers to connect to a hosted page on the control system running the SIMPL program. The SIMPL program defines the Device Driver Wrapper modules. The tool creates the devices.json file and allows for driver properties to be configured after connecting to the device (such as the a driver for the Phillips® Hue® device). The tool is used with the Crestron Device Driver Configuration Socket API SIMPL module running on a control system to configure the driver via a GUI.

Refer to the following sections for more information on using the Crestron Device Driver Configuration Tool.

Get the Configuration Tool

When creating a SIMPL program or module, add the Crestron Device Driver Configuration Socket API module to start and stop the configuration server. For more information on using this module, refer to its help file in SIMPL.

To open the Configuration Tool, download the latest Crestron Drivers SDK release. After extracting the SDK package, navigate to the ConfigTools directory to extract and open the device-driver-configuration-tool zipped package.

Deploy the Configuration Tool

The following deployment options are available depending on the control system model used.

Load the Tool via Crestron Toolbox (3‑Series/4‑Series Only)

1. Extract the contents of the zipped configuration tool archive folder to a folder with the same name as the archive. The folder structure must match device-driver-configuration-tool/device-driver-configuration-tool/[contents].

2. Open the System Information function in Crestron Toolbox software and connect to the control system. For more information, refer to the Crestron Toolbox help file.

3. Navigate to Functions > Web Pages and Mobility Projects.

4. Ensure the Enable Web Server check box is selected.

5. Select Folder as the Project Format.

6. Select Send. The page becomes accessible after the upload finishes.

Load the Tool via SFTP (3‑Series/4‑Series Only)

1. Extract the contents of the zipped archive folder to a folder with the same name as the archive. The folder structure must match device-driver-configuration-tool/device-driver-configuration-tool/[contents].

2. Connect to the control system using an SFTP client.

3. Move the extracted folder contents to the following directory on the control system: /html/device-driver-configuration-tool/[contents]. The page becomes accessible after the upload finishes.

Load the Tool via the Web Configuration Interface (VC-4 Only)

1. Navigate to the VC-4 web configuration interface as described in the Crestron Virtual Control Product Manual.

2. Navigate to Settings > Program Library.

3. Create a new program (or edit an existing program) to deploy the tool.

4. In the dialog box for the program, either upload the zipped archive of the configuration tool or add the contents of the zipped archive to an existing configuration pages archive that will be uploaded.

5. Update or save changes to the program.

6. Create a new room (or edit an existing room) that will run the program.

7. Open the Status tab and select the room created in step 6.

Access the Tool

Following deployment, the Crestron Device Driver Configuration Tool can be accessed at the following locations:

• 3-Series® and 4-Series® Control Systems: https://[ipaddress]/html/device-driver-configuration-tool/index.html.

• Crestron Virtual Control (VC-4): https://[ipaddress]/VirtualControl/Rooms/[room-id]/Html/device-driver-configuration-tool/

The tool will immediately attempt to connect to the host control system after it loads. If a connection cannot be established, the search process ends and the user can either reattempt the connection or edit the server address. Upon successful connection, the tool prompts for the system admin credentials. The tool can be used after authentication is successful.

Install and Manage Entity Model Drivers

Once the Crestron Device Driver Configuration Tool has been deployed, entity model drivers can be installed and managed directly from the tool as described in the following procedures.

Upload a Driver

Uploaded drivers are saved in the program's /user/ folder (for 3-Series and 4-Series control systems) or [vc4-install-path]/RunningPrograms/[room‑id]/user (for VC-4).

To add a new driver instance with the upload:

1. Select Add Driver.

2. Insert an Id for the new driver instance.

3. Select Upload Driver and then choose the corresponding driver file.

4. Select Submit.

To upload an existing driver instance:

1. Select Upload Drivers.

2. Select Upload Driver and choose all driver files that should be uploaded.

3. Select Upload.

Add a Driver Instance

To add a driver instance manually:

1. Select Add Driver.

2. Follow the instructions provided in the dialog box that displays. The associated driver configuration dialog box is displayed following the configuration.

To add a driver instance from an unassociated module:

1. Select the Unassociated tab.

2. Locate an unassociated item on the control system side. This is a module that is searching for a driver by its Id but it cannot be found.

3. Select Actions, and then select New driver for unassociated module.

4. Follow the instructions provided in the dialog box that displays. The associated driver configuration dialog box is displayed following the configuration.

Configure a Driver Instance

A driver instance must be configured after it is instantiated. This configuration serves as a replacement for the user attributes of the previous driver implementation. Drivers that are not configured (as indicated by a "Not Configured" status) are not ready for control.

To configure a driver instance:

1. Select the Devices tab.

2. Select Actions for the device that should be configured.

3. Select Configure from the menu that is displayed.

4. Follow the configuration instructions provided in the dialog box that displays.

5. Once configuration is complete, ensure that the driver reports a "Running" status to indicate that it is ready for control.

Offline Configuration

When online configuration is not possible via the Crestron Device Driver Configuration Tool, the following workflow can be used for offline configuration. This workflow creates (or appends to) the file that the driver configuration manager for SIMPL uses to load drivers. This is the same file generated and used by the graphical tool. The file may be updated during execution by the SIMPL driver manager when driver settings change (sometimes by the driver itself).

Load the Driver

To enable the driver within SIMPL, the following loading requirements must be met:

• The driver package file (.pkg) must be uploaded to a control system using the Crestron Toolbox™ software File Manager or SFTP.

• The driver must be assigned a unique ID and it should be listed in a devices.json file along with its configuration values.

• The JSON file must be uploaded to /user/Crestron.DeviceDrivers.Simpl/AppN/, where "N" is the application number.

The program can now be started and the driver can be loaded.

Populate the JSON File

The devices.json file should be formatted as follows:

{
  "Drivers": {
    "driver-id-here": {
      "PackagePath": "/user/path/to/Driver_File.pkg",
      "Settings": {
        "Configuration": {
          "ConfigurationIdGoesHere": "ConfigurationValueGoesHere",
          "ConfigurationId2GoesHere": "ConfigurationValue2GoesHere"
        }
      }
    },
    "another-driver-id": {
      "PackagePath": "/user/path/to/Driver_File.pkg",
      "Settings": {
        "Configuration": {
          "ConfigurationIdGoesHere": "ConfigurationValueGoesHere",
          "ConfigurationId2GoesHere": "ConfigurationValue2GoesHere"
        }
      }
    },
    "different-driver-id": {
      "PackagePath": "/user/path/to/Different_Driver_File.pkg",
      "Settings": {
        "Configuration": {
          "ConfigurationIdGoesHere": "ConfigurationValueGoesHere"
        }
      }
    }
  }
}

Multiple driver entries can be added with unique keys (duplicating the "driver-id-here" entry shown in the code above). The driver IDs are used in the SIMPL modules to link to the driver instances.

For each driver instance, perform the following steps:

1. Assign a unique driver ID to the driver instance (using the "driver-id-here" entry shown in the code above).

2. Enter the full path to the driver .pkg file on the control system for the "PackagePath" value.

3. Add configuration IDs and values to the JSON file based on the information contained in the driver DAT file (inside the package file).

Additional information about configuration items is provided in the sections that follow.

Obtain Configuration Items

Configuration items are obtained via the driver DAT file, which is in JSON format.

The DAT file must first be extracted from the driver package file. The package file is a standard ZIP file that can be opened by any compatible extraction tool. Alternatively, renaming the file to include a ".zip" extension allows it to be extracted via Windows® Explorer.

Ensure that the driver supports offline configuration by checking the following:

• It is an Entity Model driver (the DAT file must contain "driverSchemaVersion": "2.0")

• It indicates that offline configuration is available (under the "configuration" key, "isNotOfflineConfigurable" must be set to false or omitted completely).

If the offline configuration is supported by the driver, configuration.items must then be retrieved from the DAT file. Note the following:

• Each item has an id property. This property is the key for the item in the configuration dictionary.

• The programmer must provide the value for the key. Values are always specified as strings, even if the value inside the string is a number.

• If an item does not list "required": true, then it is optional and may be omitted.

• If an item's value subobject has a defaultValue property, then it should be used if another value is not required. The defaultValue property still must be part of the configuration sent to the driver.

• The minValue and maxValue properties indicate the range of a numeric property or length limitations of a string property (if "hasRange": true).

Configuration Item Value Types

The following value types are permitted for configuration items:

• None: Message for the installer, no value is provided

• String: A generic string

• Number: A numeric value (limited to 0–65535 for SIMPL compatibility)

• Boolean: A true or false value

• Hex: A hexadecimal number in base 16 form with no leading "0x" or trailing "h" (limited to 0000–FFFF for SIMPL compatibility)

All values are specified as strings in the JSON file (even Boolean values).

Usage Context

Usage context is provided for the following items:

• If an item specifies "usageContext": "Com.ChannelId", it indicates that the value is a string that must match the string parameter or input of a Crestron Device Driver Serial Connector module in the SIMPL program.

• If an item specifies "usageContext": "Cec.ChannelId", it indicates that the value is a string that must match the string parameter or input of a Crestron Device Driver Cec Connector module in the SIMPL program.

• If an item specifies "usageContext": "Data", it indicates that the value is provided by the driver during operation and is written back to the driver on startup. The SIMPL driver manager handles these operations automatically. If the item also specifies "required": true, specify an empty string as the value.

Sample JSON Configuration

The following sample JSON configuration is provided for reference.

{
    "Drivers": {
        "hue-bridge": {
            "PackagePath": "/user/Platform_Philips_Hue_IP.pkg",
            "Settings": {
                "Configuration": {
                    "_Host_": "<ip-address>",
                    "_Port_": "443"
                }
            }
        }
    }
}

Tips and Best Practices

The following tips and best practices should be used when loading Crestron Drivers:

• Different versions of the same driver package file (.pkg) will have the same filename, so they often can be swapped or upgraded without modifying the programming.

  • To update driver file versions on the control system, stop the running program, swap the driver .pkg files (though File Manager or SFTP), and then restart the control system.

  • Occasionally, the module version used in SIMPL will need to be swapped or updated to support the latest driver versions. Refer to the driver SDK version listed on the Crestron Drivers portal and SDK Framework Comparison Matrices.

• IP-controlled displays should be connected via wired Ethernet to ensure reliability. Some displays do not communicate reliably when connected only over Wi‑Fi® communications.

• IP-controlled displays that use Wake-on-LAN (WOL) often have a long power on/startup period (over 30 seconds) before they can receive IP commands. Therefore, it is recommended that these drivers should be used primarily for power on or power off applications only, since other commands (such as volume control) cannot be issued until the power on period ends. Alternative solutions should be considered if other functions like input switching or volume control are required. For more information on WOL devices, refer to Using Wake On LAN (WOL) to turn on a PC from a Control System.

• The LG® 2018 Ethernet v1.4 and Samsung® 2018 IP Demo v1.3 modules available in the Application Market are essentially older versions of the Crestron Drivers Display Ethernet modules (but without the ability to specify <DriverFile$>, as they internally reference the DLL file loaded to \SIMPL\app##\ along with the program files). Therefore, these modules will not receive any updates and cannot be placed in a program alongside newer Crestron Drivers modules. In these cases, use the latest Crestron Certified Drivers Display Ethernet vX.X (cm) module available in SIMPL with drivers from the Crestron Drivers portal.

Troubleshooting

Contact Crestron True Blue support via phone, email, or chat as described at www.crestron.com/Support to report any issues when using existing Crestron Drivers.

For SIMPL programs and modules, perform the following debug steps prior to submitting a support request:

1. Connect to the control system with SIMPL Debugger.

2. Latch the <EnableLogging> signal high.

3. Reattempt <LoadDriver> and observe the messages in the SIMPL Debugger trace.

4. Latch <EnableTxDebug> and <EnableRxDebug> and observe the communication.

5. Save the SIMPL Debugger trace to provide within the support request.

6. Run the Information Gathering Tool for Crestron® Devices and provide the results along with the SIMPL archive and SIMPL Debugger trace.