Best Practices

Crestron recommends the following best practices for developing drivers. Best practices are grouped by development tasks and driver SDK architecture versions.

General Information

The following best practices pertain to any version of the driver SDK architecture.

Driver Development

There are numerous different types of device drivers that can be developed using Crestron Driver framework. The framework currently supports

Audio Mixer
AV Receiver
AV Switcher
Blu-ray Disc® Player
Cable Box
Crestron Home® Extension Device
Flat Panel Display
Lights (V2 architecture only)
Multizone AV Receiver
Platform (Gateway)
Power Controller
Projector
Security System
Video Server (Streaming Media)

Additionally, more device types will be added to the framework that will enable developers to add more controllable devices that can be used by all Crestron® control platforms, including Crestron Home® OS and AV Framework™ software.

The following best practices are designed to give you the best possible result when developing drivers:

Follow the guidelines listed by Microsoft® in C# Coding Conventions at https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions.
Name drivers in the format of “DeviceType_Manufacturer_BaseModel_Transport”. For example, an AV Receiver driver could be called “AvReceiver_Anthem_MRX-720_IP”.
Allow the framework to do most of the work:
- If you have added all of the commands into the driver JSON correctly, including any response headers and feedback, the framework should be able to control the device without many changes by the developer.
- If you need to change how the driver either builds or sends commands, or how the driver handles feedback, we have provided a way for this to be accomplished.
The driver can logically be broken up into four sections.
- Driver Transport: The transport used to send commands and receive responses.
- Driver Protocol: Handles how commands are built and sent to the device
- Driver Response Validation: Used to validate the responses from the connected device.
- Driver JSON: Used to input the data found in the manufacturer’s API, which is used to communicate with the connected device.
  - The manufacturer will typically provide information on how to communicate with their devices including commands, responses, and communication details.
  - Properly constructed JSON is essential for getting most of the work done in the driver.
If this is not an IP driver, do not assume that all calls to ResponseValidation and DataHandler will contain the full message; it might come in byte-by-byte. Therefore, the driver should be written to collect the data until a full message is captured. This should be done in ValidateResponse(…).
- Most serial protocols will give a clear delimiter for the end of each response, which generally appears as a carriage return.
- Check the manufacturer documentation to ensure that you gather the response up to and including the delimiter before processing the response.
The WarmUpTime should consider the amount of time it takes for the device to power on and the amount of time it takes until the driver is able to control the device.
- For example, a TV that uses Wake On LAN to power on might take five seconds to show an image but an additional ten seconds until the TV responds to any queries or it is controllable. The WarmUpTime in this case should be 15 seconds.
The CoolDownTime should consider the amount of time it takes for the device to completely shut off and it is able to be powered back on again.
- For example, a receiver takes one second to shut off but an additional four seconds until it responds to a PowerPoll and it can power back on. The CoolDownTime in this case should be 5 seconds.
- Lamps used by these devices can easily be damaged if they are not sufficiently cooled before attempting to restart.
- Most manufacturers build in safeguards, but users should not feel as if there could be an issue with their equipment. The cooldown time is one way we can inform a user that the projector requires more time to cool down before it is powered on again.
The GUID listed under GenralInformation in the JSON should be unique. Duplicates can happen when copying the JSON of one driver to create another driver. Visual Studio can create a new GUID in the registry format under Tools > Create GUID.
Send commands to the device using the queuing logic instead of directly through the transport. Build the CommandSet and send it using SendCommand().
If a device requires setup in its settings to enable control, concise instructions should be provided in the User Attributes section in the JSON. Refer to the following sample code.

Copy

"UserAttributes": [
    {
        "TypeName": "MessageBox",
        "ParameterId": "Configuration Notice 1",
        "Label": "Setup Instructions",
        "Description": "To enable IP Control on the device go to Home > Settings > Wireless and Networks > External Control > IP Control > set to 'ON'",
        "Persistent": false,
        "RequiredForConnection": "None",
        "Data": {
            "DataType": "",
            "Mask": "",
            "DefaultValue": ""
        }
    }
]

Avoid calling functionality that may not have existed in an older version of the driver framework to prevent MissingMethodExceptions when loading driver into systems containing an outdated framework version.
If a driver uses anything that implements IDisposable (such as a CTimer used in a driver), it must be disposed of in an override of Dispose() and the base method must be called. Dispose() can be overridden in the protocol class.
Check if EnableLogging is true before sending a string to the Log() method. Although the Log() method already contains a check for EnableLogging, checking beforehand prevents allocating a string in memory that will not be logged if EnableLogging is disabled.
Methods that have a potential to cause exceptions should be placed in a try catch with a clear logging and a stack trace for easier field debugging.
- As an example, attempting to parse from a string into an int. If there are no numeric values in the string this will throw an exception.
- Visual Studio 2008 does not support TryParse.
For APIs where a single poll command can specify multiple values, such as mute state, volume level, current input, and power status, the driver should only specify that command as a poll command, and must set the command group of ValidatedRxData in ValidateResponse(…) to the command group of that poll command to prevent time-outs. Along with this, ValidateResponse must directly call Protocol.ChooseDeconstructMethod and Protocol.DeConstruct<Feature> on all data that is not part of the single poll command.
- This is common for drivers that respond using JSON or HTML to have multiple statuses within the response. If this is the case, poll for one status and process all of the statuses at once.
- This can be done by overriding DataHandler, deserializing the response, formating a response for each status, and individually calling base.DataHandler for each.
- Alternatively, deserialize each response in ResponseValidation, then process and call deconstruct for each status except the one polled for. For example, if polling for power status and the device returns power status and mute status, process the mute status and call deconstructMute and return ValidatedRxData with power status.
Set WaitForResponse to true on all drivers that use HTTP/HTTPS and ensure ValidateResponse(…) always returns ValidatedRxData.Ready/Ignore to true on each call to it.
Simulating feedback can be done by calling DeConstruct<Feature> methods with the string they expect.
- Simulating feedback may be needed if the device takes a long time to respond to a polling query. This would occur mostly to ensure a good user experience.
- Since all devices are different, the driver developer should a user to feel like all equipment looks and acts the same when using Crestron hardware.
- Sending the expected feedback value to the framework as “fake” is essentially helping the device by telling the user what they did and eventually updating the feedback with the actual status from the device.
Avoid calls to CrestronEnvironment.Sleep(…).
- This creates a new thread and can be an issue if multiple instances are creating new threads.
- This can have negative consequences depending on how many instances of the driver your program is using.
When getting or creating an HttpWebRequest object, request.KeepAlive = false; must be added to the code prior to executing the request. This helps to prevent a memory leak in the .Net SDK.
- Each time an HTTPS URL is queried using the HttpWebRequest object, a timer is created that causes the authentication data used for the connection to expire. There is a bug that causes the timer to never fire, so one Timer object and one DelayPromise object will stay in memory for the life of the program or until the system runs out of memory and restarts.
- By setting the KeepAlive (CLR) property to false, it prevents the system from setting up the Timer and DelayPromise objects, preventing the memory leak.
Ensure that all IsSupported flags are set before the driver is initialized. Updating flags after they have been set is not supported.
When using .NET objects with callback methods (such as Timer callbacks), use a Try/Catch block to catch and log any exceptions. Any unhandled exceptions may crash the driver or system. These equivalent objects in the SIMPL # SDK have these protections built in.

AV Receiver Inputs

AV Receivers use the following rules:

The only INPUT connector types that should be used are GenericAudio or GenericAV.
Devices are limited to a maximum of 50 supported Inputs.
Attempt to choose the Standard Command that closely matches the Button Label or Display Name.
The preferred Standard Command is INPUT1 – INPUTx . The friendly name should resemble the name as notated on the device buttons or menu/device display.
- Input 1 = 1800
- Input 2 = 1801
- Input 3 = 1802
All Video inputs that support audio will need to specify with connector values of GenericAV (150) and must be specified under the audio section as GenericAudio (130) with a friendly name that includes “Audio Only."
- If the input is Audio only, then “Audio Only” should not be applied to the friendly name.
All Video inputs that do not support audio will need to specify with connector values of GenericVideo (160).
All audio inputs must be specified under the audio section as GenericAudio (130) with a friendly name that includes "Audio Only."
The “Friendly Name” field is a way to identify the input as it is represented by the device. You may use the display name or name that is printed on the remote button. If it is an audio only or the audio portion of the video input, then "Audio Only" will need to be added to the friendly name.
If an audio only input has the ability tp assign a video input to that source, such as a CD, Tuner, or a Phono, then these inputs need to be supported as GenericAV. This could be accomplished by using a standard command type of Input1 ~ 15 (or IN1 ~ IN15 for IR) and specifying the friendly name as listed for that input source (such as CD, Tuner or Phono). This would allow data to be passed through the packaging script and would allow support within Crestron Home and other applications.
Use actual connectors and do not use the GenericAudio and GenericAV Audio Video Enums to define outputs.
Multizone Receiver Inputs should be mapped exactly the same as the main zone.
- All available audio and video inputs must use the same standard commands as their main zone selections use. This will ensure that all input routes can be properly made in products that consume the drivers.
- Be aware that not all inputs available in the main zone can be selected in the remote zones. Refer to the manufacturer's user manual to determine which inputs can be selected from the remote zones.
- Check if the receiver will also allow for video source inputs to be selected in the remote zones.

Crestron Home Driver Limitations

Drivers used within Crestron Home should not include any DLL files that conflict with DLL files that are already loaded within Crestron Home. Loading these DLL files in the driver may cause issues with its functionality.

The current version of Crestron Home is running .NET Framework version 4.6.2.

NOTE: If any of the following DLL files must be used in the driver for any reason, use ILMerge to merge the additional DLL files into the driver DLL before packaging it.

Refer to the following list of DLL files loaded within Crestron Home:

Newtonsoft.Json
System.AppContext
System.Collections.Concurrent
System.Collections
System.Collections.Immutable
System.Collections.NonGeneric
System.Collections.Specialized
System.ComponentModel
System.ComponentModel.EventBasedAsync
System.ComponentModel.Primitives
System.ComponentModel.TypeConverter
System.Console
System.Data.Common
System.Diagnostics.Contracts
System.Diagnostics.Debug
System.Diagnostics.FileVersionInfo
System.Diagnostics.Process
System.Diagnostics.StackTrace
System.Diagnostics.TextWriterTraceListener
System.Diagnostics.Tools
System.Diagnostics.TraceSource
System.Diagnostics.Tracing
System.Drawing.Primitives
System.Dynamic.Runtime
System.Globalization.Calendars
System.Globalization
System.Globalization.Extensions
System.IdentityModel.Tokens.Jwt
System.IO.Compression
System.IO.Compression.ZipFile
System.IO
System.IO.FileSystem
System.IO.FileSystem.DriveInfo
System.IO.FileSystem.Primitives
System.IO.FileSystem.Watcher
System.IO.IsolatedStorage
System.IO.MemoryMappedFiles
System.IO.Pipes
System.IO.UnmanagedMemoryStream
System.Linq
System.Linq.Expressions
System.Linq.Parallel
System.Linq.Queryable
System.Memory
System.Net.Http
System.Net.NameResolution
System.Net.NetworkInformation
System.Net.Ping
System.Net.Primitives
System.Net.Requests
System.Net.Security
System.Net.Sockets
System.Net.WebHeaderCollection
System.Net.WebSockets.Client
System.Net.WebSockets
System.ObjectModel
System.Reflection
System.Reflection.Extensions
System.Reflection.Primitives
System.Resources.Reader
System.Resources.ResourceManager
System.Resources.Writer
System.Runtime.CompilerServices.Unsafe
System.Runtime.CompilerServices.VisualC
System.Runtime
System.Runtime.Extensions
System.Runtime.Handles
System.Runtime.InteropServices
System.Runtime.InteropServices.RuntimeInformation
System.Runtime.Numerics
System.Runtime.Serialization.Formatters
System.Runtime.Serialization.Json
System.Runtime.Serialization.Primitives
System.Runtime.Serialization.Xml
System.Security.Claims
System.Security.Cryptography.Algorithms
System.Security.Cryptography.Csp
System.Security.Cryptography.Encoding
System.Security.Cryptography.Primitives
System.Security.Cryptography.X509Certificates
System.Security.Principal
System.Security.SecureString
System.Text.Encoding
System.Text.Encoding.Extensions
System.Text.RegularExpressions
System.Threading
System.Threading.Overlapped
System.Threading.Tasks
System.Threading.Tasks.Parallel
System.Threading.Thread
System.Threading.ThreadPool
System.Threading.Timer
System.ValueTuple
System.Xml.ReaderWriter
System.Xml.XDocument
System.Xml.XmlDocument
System.Xml.XmlSerializer
System.Xml.XPath
System.Xml.XPath.XDocument

Driver SDK V1 (RAD Framework)

The following best practices pertain to the RAD Framework (V1) SDK architecture.

Troubleshooting

Many issues relating to the driver not working properly can be found in the driver JSON. Often, a driver's JSON will pass a validation script, which ensures that the JSON can be parsed. However, if any of the objects are out of place, the driver cannot properly use them.

The following image illustrates a properly constructed JSON schema.

JSON Schema

When you run a JSON viewer, the JSON schema should appear as shown in the image above. In the case that your device is not an AV Receiver, your JSON would not have the AvrZoneData object. Otherwise, everything else remains the same.

Input definitions can cause issues that can be problematic if not properly configured.
- When defining AV Inputs alongside Audio Only inputs, make sure that they use the same Standard Command enum values. These values are referred to as “type” in the definitions. Ensure that when selecting an input, the correct command gets sent for both AV and Audio Only inputs.
- Crestron Home also uses these “types” to map their input routing when configuring a new system.
- The standard command types should map the same through all remote zones as well. An AV Receiver that supports multiple zones should map all input selections to the same standard command types as the main zone.
Aside from JSON issues, many issues could be related to any method overrides in the driver.
- If you override a method in the driver, you still must make the method run without any errors. If the override is causing any exceptions in the driver, you may need to add a try/catch in order to isolate the issue. If an exception is thrown, at least the driver will continue to run.
- If there is an exception, even in a try/catch, you should eliminate the exception using proper programming.
- Integer conversions are common places where exceptions are thrown if the string you are trying to convert does not contain a number.
- When logging exceptions, log a stack trace on the exception. This is helpful for identifying the issue and to show another developer where to begin.

Have feedback on this document? Contact docfeedback@crestron.com.

All brand names, product names and trademarks are the property of their respective owners. Certain trademarks, registered trademarks, and trade names may be used to refer to either the entities claiming the marks and names or their products. Crestron disclaims any proprietary interest in the marks and names of others. Crestron is not responsible for errors in typography or photography. Specifications are subject to change without notice.

Best Practices

General Information

Driver Development

Device Inputs

AV Receiver Inputs

File Storage

Control Systems

Crestron Virtual Control (VC-4)

Crestron Home Driver Limitations

Driver SDK V1 (RAD Framework)

Driver Overrides

Troubleshooting