Introduction

Crestron Home (Home from hereon) continues to be a great success, bringing a rich Crestron automation experience to homes that may have previously had to compromise for a more “consumer” automation solution.

However, we are still in the relatively early days for the product and many of the current installations are starting to reach the point where updates are desirable or required. The Home operating system is capable of automatic updates but the myriad device drivers, which provide the glue between Home and the 3^rd party components around the house, cannot currently be updated automatically. For the sake of clarity, we are discussing updates of the same driver to a new version – as opposed to changing one driver for an entirely different device or model.

In some circumstances this is an inconvenience. In others it can lead to unnecessary support calls. At worst, the driver update process can leave a Home system in a very sorry state requiring roll back to a known working state or – at its most extreme – a fresh install.

This document will first outline the process for safely updating a driver in Home, and then, for the more technically minded, explain why this is necessary.

The Safe Process

Before we start, there is no pretence here – this isn’t a convenient or streamlined process. For various reasons (outlined later) Home cannot, at the present time, simply replace a driver without some user intervention.

So, the first question to ask is, do I need to update the driver at all? Our advice here would be to get confirmation that a driver fixes some known issue or provides required functionality before updating. Simply updating because there is a new, higher, version number may not be necessary. However, if you do need to update your driver, these are the steps that Ultamation recommend:

Step 1: Save your config
I mean, what could go wrong?
You really want to do this before any driver changes – it’s quick and easy.

Step 2: Remove the original driver COMPLETELY.
Using the Home setup app, track down every, last instance of the driver you have configured on the system. For something like a projector driver this may be as simple as a single instance. For something like a lighting driver, you may have tens of instances. They ALL have to go. The downside here is that all routing, sequencing and programming will also be lost.

Step 3: Restart the Home system using the setup app.
You need to restart Home before you can safely pull in a new driver. There is a technical reason for this (see below) but, in a nutshell, this allows Home to tidy up references and ensure the system integrity in maintained.

WARNING: DO NOT reboot the processor by pulling the plug, or typing “Reboot” at the console, as this will restart the processor without any of the vital housekeeping. This is probably one of the best ways to ruin your Home configuration and can lead to all manner of oddness, such as a driver being loaded despite not being visible in the setup app.

Step 4: Confirm that the old driver is really gone!
This is just a verification that the previous steps were successful, but if you don’t do this you run the risk of thinking that you’re running the latest driver, when Home is actually still running the original. (see below for the technical “why”)
Unfortunately, there’s no “easy” way to do this and it involves looking at the Home processor’s file system to check that the driver isn’t shown under “user\data\UsedThirdPartyDrivers” as shown below:

Step 5: Load the new driver
Either grab the driver from the Crestron driver portal (which will appear in the Home setup app) or sideload the updated driver (covered elsewhere).

Step 6: Reconfigure the driver.
You will now need to recreate all routes and programming ties that were lost during driver removal.

You should now have the updated driver running correctly in Home.

There is clearly a lot of scope for addressing the current challenges of driver updates in Crestron Home and Ultamation have written this guide in response to the increasing number of questions we receive about updating drivers. As Home continues to grow and older systems receive maintenance updates then we expect Home will be enhanced to streamline the driver update process and, hopefully, make this guide redundant.

 

Why All The Pain? - The Technical Reasons

Why isn’t this automatic?
We’re going to brush aside the “but xyz have been doing it for years!” because it’s silly to compare apples and oranges. XYZ probably has a completely different driver architecture to Home so the rules/constraints are naturally very different. But specifically for Home, there are times where a driver could be updated, at least semi-, autonomously. The trouble is, there are numerous ways in which a driver update could break a configuration which would require manual intervention. The list includes:

• Deprecated features
  What does Home do with that command that just disappeared!?
• Changes to I/O config
  TV/CBL was just renamed to MEDIA – are they the same? Different?
• Programmable Operations/Events have been changed
  What does Home do with the actions that were programmed into sequences?

Now – those are some arguments as to why automatic updates are dangerous. But that doesn’t mean the situation couldn’t be better. Home should be able to flag that a driver update is available and perform some consistency checks to see if an update would create any configuration anomalies. If there are no issues detected, then a semi-automatic update process should be possible which would remove most of the inconvenience and fragility issues.

So many drivers for different models – They all seem the same!
That’s because they probably are. This is sadly a numbers game. If you have a driver database and you want to shout about how many drivers you have, the figure you quote is really the number of supported devices you cover, not the actual number of variations of code you have. If every Sony TV uses a protocol that is 98% consistent across all (for arguments sake, 500) models, that’s probably 1 driver, but we advertise it as 500 models – why? – because it means an integrator can verify that a specific model is supported, but also because is makes the driver database appear bigger. It’s not helpful when you’re searching for an elusive feature that doesn’t seem to work correctly on the driver you’re testing, but that’s the way it is. Hopefully there will be something in the future to allow us to see which drivers share a common base so integrators can test once; and move on.

Why do we have to remove the old drivers?
This one is a bit technical and we need to make a distinction between the driver information (the entry in the Home driver list) and the driver code (the running code once a driver has been “loaded” into the memory of the Home processor). This problem lies deep within the operating system (below Home itself). Once the code is loaded into memory, it is there for good. The underlying OS cannot (without architectural changes that Crestron have already considered and dismissed) load updated driver code “over” the original. If you leave a single instance of a driver around then, as soon as Home reboots, it will reload the original driver and you’re back to where you were. They ALL have to go.

Why do we need to reboot Home before loading the new driver?
Read the reason above. The only way to clear the Home processor’s memory of the old driver is to restart the Home process (i.e. a reboot, or program reset).
Additionally, you cannot always rely on drivers being cleanly removed when they are taken out of the setup app config (especially Platform drivers!). This isn’t only true for driver updates, but also when modifying driver properties through user attributes. If in doubt, after you’ve made changes to the Crestron Home configuration, check with a clean restart!

I think I’ve messed up the Home config. What are my options?
The safest bet is just to restore the config you made in step 1. On rare occasions Home may not even boot to the point where you can restore a cloud config though, more often than not, Home will revert to a factory state if it detects serious problems. If you really find yourselves at the edge of the world, call Ultamation and we can try to assist.

But Home says it’s updated and I didn’t do all of this nonsense.
It’s easy to think Home has updated your driver when it hasn’t. For the reasons already discussed, this is what can happen:

Because Home cannot replace code at runtime (i.e. without a restart) the old code is still running even though Home has processed and imported the new driver’s information. In the future, we hope that Home will flag this discrepancy and inform the integrator that the driver update is not complete until the system has been restarted.

As a multi–award winning company specialising in high-end Crestron home automation we are used to writing modules for jobs we are working on.   With one of the, globally, few Gold Crestron Master Programmers at the head of our team, we excel in the more challenging modules and have written drivers for equipment that had previously been considered too complex to integrate. 

We now enjoy a reputation for high quality, tried and tested modules which we have made available to other Crestron programmers and integrators, both saving them time in completing jobs and being able to offer sophisticated integration, that otherwise might have been unachievable for their clients.

Ultamation is our vehicle to deliver these products to you!

Along with requests from manufacturers and integrators to develop modules for their products, we’re constantly looking to provide support for innovative solutions – from car turntables to steam rooms.

We also develop software solutions for the Crestron programming community, such as the hugely popular “Theme Creator” for UI designers and the “SIMPLified” programmer’s assistant.

Introduction

Far from what you might think from the title, this article is not about poking fun at the world’s leading automation system. Far from it: Crestron is the only platform that has successfully made the transition from proprietary development environments and niche, specialised programming, to mainstream software development practices.  This article covers one aspect of that transition by describing one approach to “unit testing” – the practice of repeatedly testing small elements of a larger system to ensure they satisfy their design parameters – using “mock” objects.  This gives confidence that your code, when employed in a larger system, will yield the expected behaviour.