Crestron Home OS Testing

This topic describes how to create a simple Crestron Home® OS system for testing and validating drivers within Crestron Home. The system must be configured and all applicable devices must be added prior to testing.

NOTE: While building a test system, ensure that all drivers all imported properly into Crestron Home so that no errors occur.

For general information related to Crestron Home, refer to the Crestron Home OS Product Manual.

Configure a Crestron Home System

Crestron Home is configured using the Crestron Home Setup app. For more information on configuring a Crestron Home system, refer to Configure a Crestron Home System in the Crestron Home OS Product Manual.

Specific information regarding configuration related to device drivers is provided in the following topics.

Device drivers should be side loaded into the control system running Crestron Home prior to adding the corresponding devices to the system. Custom drivers can be loaded using FTP or the Device Learner tool (IR drivers only).

Load Using FTP

  1. Connect to the Crestron Home processor over FTP or by using the File Manager tool in Crestron Toolbox.
  2. Upload the custom driver package file or IR file into the Crestron Home processor's \User\ThirdPartyDrivers\Import directory.
  3. Navigate to the driver using the Third Party Devices menu in the Pair Devices screen. The screen refreshes automatically to display the driver after it has been loaded into the system.

Load Using Device Learner Tool

  1. Open the Device Learner tool in Crestron Toolbox™ software.
  2. Navigate to File > Send .PKG to Device.
  3. Save the driver package file to the User Database.
  4. Select the Crestron Home processor using the Address Book tool and then select OK. Once the transfer is complete, a pop‑up dialog is displayed showing the package file, the device host name/IP address, and the transfer status.

    5. NOTE: The custom driver will overwrite existing drivers on the Crestron Home processor if the drivers share the same ID (manufacturer, model name, and communication type)

Reimport a Driver

If you make changes to your driver and want to reimport the new driver, you must first follow these steps to erase the old driver:

  1. Remove all instances of the old driver from Crestron Home.
  2. From the Crestron Home Setup UI, navigate to Settings > System Configuration > Reboot, and then select Reboot to restart the control system.

    3. NOTE: Do not issue the reboot console command to restart the control system. The control system must be restarted from the Crestron Home Setup UI when reimporting a driver.

  3. Import the new driver as described above.

Once the appropriate device drivers have been loaded to the Crestron Home system, the corresponding devices can be added in Crestron Home.

  • For more information on adding third-party devices, refer to Third‑Party Devices in the Crestron Home OS Product Manual.
  • For more information on adding uncontrolled devices, which are useful in simulating input sources of displays (especially if you are attempting to isolate an issue), refer to Other Devices in the Crestron Home OS Product Manual.

NOTE: When viewing driver information for third-party devices in Crestron Home, the version is taken from the DAT file and not the running DLL file.

After all devices have been added to the Crestron Home system, configure source routing for devices in the system as described in Source Routes in the Crestron Home OS Product Manual.

Testing Drivers

Once the Crestron Home system has been configured as described above, drivers can be tested by monitoring the driver for errors using a Telnet session and debug commands.

Control System Debugging

To enable debugging on the control system via Telnet:

  1. Open Crestron Toolbox™ software.
  2. Establish a Telnet connection to the control system running Crestron Home. For more information, refer to the Crestron Toolbox help file.
  3. Open the Text Console tool.
  4. Issue the ENABLEPROGRAMCMD command.

While testing, keep the Text Console session open and issue the ERR command to view error logs and other messages for debugging.

Proceed by testing each driver function and verifying the result in the Text Console tool. Look for the following while verifying driver functions:

  • During source routing, verify that the source route is correct and the system responds as expected.
  • Verify that the commands sent are the expected commands.
  • Verify the command responses are correct and the driver is updated as expected.
  • Watch for odd and unexpected commands or errors.

Additional verification should be exercised when performing volume ramping over hardware keys, since Crestron Home currently sends an unmute command on every iteration.

Preform the following tests:

  • Start with the volume range as zero. Press and hold the volume increment button until the volume scale reaches 50%. Release the button and verify the response.

    • The expected response is that the volume ramping should stop immediately.

  • Press the volume command 10 times in a row and verify that the device increments 10 steps.

    • The expected response is that the volume increments the expected 10 steps.

  • Mute the volume command, then press the volume increment or decrement command.

    • The expected response is that the volume unmutes and increments or decrements the expected value.

  • Increment the volume command to 100%.

    • The expected response is that both the device and the driver return 100% feedback.

  • Decrement the volume command to 0%.

    • The expected response is that both the device and the driver return 0% feedback.

  • Using hardware to set the volume, ramp the volume on the device to 100%.

    • The expected response is that driver returns 100% feedback.

  • Using hardware to set the volume, ramp the volume on the device to 0%.

    • The expected response is that the driver returns 0% feedback.

Debug Command Overview

This section explains debug commands that may be used within Crestron Home or in a custom solution to troubleshoot potential issues with the driver.

Debug Commands for SIMPL# Drivers

The debug messages for SIMPL# drivers are broken into three separate commands, which allows you to enable each logging mechanism independently of one another for customized results. An informational command is also provided.

  • ccdinfo: Reports the driver ID, driver name, type, and version.
  • ccdlogging: Enables general logging within the driver and is required to be enabled in order to see CCDTxDebug and CCDRxDebug data.
  • ccdtxdebug: Enables Transmit string logging.
  • ccdrxdebug: Enables Reception string logging.

NOTE: The naming of these debug commands are dependent upon the version of the SDK framework. Older version of the framework may use the commands radinfo, radlogging, radtxdebug, and radrxdebug.

Debug Commands for Hot-Swappable Drivers

This section describes commands that can be used to debug hot-swappable drivers.

The Ch logger drivers command lists all drivers present within Crestron Home.

Copy 
Drivers                         Warning (Default) (Partial)
Drivers\Capabilities            Warning          
Drivers\Catalog                 Warning          
Drivers\HostManager             Trace            
Drivers\InterProcessor          Warning          
Drivers\TSR 310                 Warning (Partial)
Drivers\SampleDriver            Warning (Partial)
Drivers\Uninitialized           Warning (Partial)

The Ch logger drivers {drivername} {setlevel} {setscope} command turns on logging for a specific driver within Crestron Home. For example, issuing Ch logger drivers 'Drivers\SampleDriver' 'trace' would turn on trace logging for the 'SampleDriver' driver.

The setlevel command attribute allows each logging mechanism to be turned on independently for customized results. The default log level is Warning.

  • Info: The information logging level reports significant events that occurred, such as end user actions.
  • Warning: The warning logging level reports issues that have occurred but still allow the app or program to mostly function.
  • Debug: The debug logging level shows the execution path of the code without excessive verbosity.
  • Trace: The trace logging level outputs verbose debug messages, such as logging in a loop or logging every packet or message that is sent by or received from the device.
  • Error: The error logging level reports severe issues that may cause the app or program to no longer function.
  • Off: This argument turns off all logging.

The setscope command attribute defines the scope of a log entry in terms of visibility to an end user. The default scope is Internal.

  • Private: Log files are persisted only (such as to a log file). The log files will never be printed or outputted in a user interface other than an app that views persisted log entries.
  • Internal: Log entries are visible only by using debug tools such as a text console or shell, log file, or diagnostic app.
  • Published: Log entries are intended to be visible to an end user. Only the Information, Warning, and Error log entries will be published.

Additionally, Depth and DoNotPersist are optional attributes that can be appended to the ch logger drivers command.

  • Depth: Applies the current log setting to the subcategorized logger. A depth of "0" sets the current setting the top‑most scope or level.
  • DoNotPersist: Temporarily changes the log scope or level that does not persist beyond the current program run.

As an example, the Ch logger drivers 'Drivers\SampleDriver' command would be used to see the current log level set on the driver.

Copy 
Drivers\SampleDriver            Trace 
Drivers\SampleDriver\52028      Trace

Additional Logging Commands

Additional logging commands are provided for Crestron Home:

  • enableprogramcmd: Enables debugging to the Text Console (Telnet Session)
  • progres -p:0: Restarts the Crestron Home controller.
  • stopprog -p:0: Stops the Crestron Home controller.