The Ultamation Help Centre

We're very proud of the reputation Ultamation has for exemplary customer support.  As they say, talk is cheap, and it's not the fact that you say you provide first-rate support, it's whether customers get a quick response to their queries and how far you go to resolve the problem.  We work very hard, often responding to customers out-of-hours and walking them through configurations or diagnostics - usually without charge.

While we firmly hold that the human element to customer support is crucially important, it's important to make information as accessible as possible as this means that potential issues can be avoided without engaging with support at all at times and we can provide thorough responses to common problems without rewriting the same information out for the 10th time, simply by linking relevant, already documented, information.

To that end, we have introduced the Ultamation Help Centre which is a repository of documents that we will continuously update with useful info.  The information isn't public, and you will need to register on the portal to access the documents, but this is a property of the platform we're using and we do not use any personal information gleaned from creating an account.  Sadly, this account is not linked to existing Ultamation shop accounts.

We've also moved over to a new ticketing system for support tickets (generated by emailing This email address is being protected from spambots. You need JavaScript enabled to view it.) and the new system gives registered users a way to keep track of their cases.  If you email This email address is being protected from spambots. You need JavaScript enabled to view it., you will automatically have an account created by the platform to that you can track your case.

To access the Ultamation Help Centre, please follow the link below.

Ultamation Help Centre

As an incentive, we've already started writing up the new Apple TV control FAQ so if you're quick off the mark, you can get access to otherwise unreleased information about the new CompanionLink drivers for Crestron and Crestron Home.

We're also publishing recipes for the Crestron Home wildcard drivers which provide simple "hacks" for giving your clients capabilities that can't by offered by your competition.

Wildcard Recipe: Sending Commands to Display Endpoints

Problem

Your Crestron Home project is using a 3rd party AV switcher but you haven’t been able to use the full capability of sending commands to the displays to turn them on and off.

Solution

The Ultamation Wildcard modules can be used to send these commands to the AV switcher by integrating the commands into hidden quick actions which are triggered when a media zone is powered on or off.

1. Add the appropriate Ultamation Wildcard driver to Crestron Home - this will depend on the capabilities and communications model of your chosen AV switcher.

2. Configure your chosen commands for buttons or discrete commands (under Actions/Sequences) using the information in the table, and examples below. If you work out more commands, please let us know and we’ll add them to the table!

3. You’re in the 1-hour trial period window - give your new integration a test drive!

4. Once you’re happy everything is working, purchase a licence key for your processor for one of the wildcard drivers here… Home

5. Add the licence key to your Crestron Home configuration (under “Installer Settings”)

Command Table

Examples:

The following examples show you how format the the commands in the Installer Settings of the module.

The first element - “Label” - can be whatever you want to have displayed on the button. The other elements must be formatted exactly as shown.

Binary MoIP, using the TCP Wildcard, turn on TV on output 3

Playroom TV On|!CEC3,1\x0A

Binary MoIP, using the TCP Wildcard, turn off TV on output 3

Playroom TV Off|!CEC3,0\x0A

HDANYWHERE, using the HTTP POST Wildcard, turn off TV on output HDBT 'a'

Lounge TV Off|api/command/cecpass/a/1/|{"logicaladdress":"EF","command":"36","arguments":""}

Manufacturers vary greatly in their support for, and implementation of, CEC commands.

Kudos to Isaac Rosario of Voyager Home Systems Voyager Home Systems | Oklahoma City Metro Smart Home Installations for suggesting this really innovative integration solution and providing Binary MoIP data.

Updating Drivers In Crestron Home

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.

Controlling Devices - The Good, The Bad and The Ugly

As you can see, we write a lot of device drivers.  To do this, we have to get intimately acquainted with the protocols that a device's manufacturer has implemented to provide control of their device.  In an ideal world, these protocols would be well designed, fit for purpose and fully documented.  We're not living in an ideal world, and depending on where you look you may well come to the conclusion that things are far from ideal - in fact, there are some truly horrible protocols and implementations out there.  This article describes some of the challenges we face when implementing a protocol handler for a driver.  It's also an offer to any manufacturer that perhaps doesn't have the expertise in house to define a well-designed control protocol; Ultamation can help.

What is a control protocol anyway?

In this context, We're talking about the language that a control system, such as a Crestron processor, speaks to communicate with another device; say, an amplifier or an intruder alarm panel.

Protocols come in all shapes and sizes (more on that later) and their job is to convey commands and feedback between two devices.  the design goals should encompass:

• Be unambiguous - the protocol has to be clear and unambiguous.  You tell the device what you want, and it should understand you without any trouble.  Likewise, when the device responds, or generates unsolicited feedback, you should be able to infer what the data relates to without prior knowledge.  It's surprising how many protocols make this simple mistake.
• Be efficient - if you want a device to perform well, you need to consider efficiency or message generation and parsing.  This is an important consideration for implementing a protocol handler as you many not be able to control how rapidly messages are thrown at you, and both ends of the conversation should handle being overwhelmed gracefully.
• Consider the lowest common denominator - some developers have their favourite language and libraries.  If you work with web technologies, the path of least resistance might be an HTTPS based protocol with OAuth.  Easy for you, hard for someone trying to implement a client on a microcontroller in a language that doesn't have native support for secure sockets, or a convenient way to gather an authentication token from the account holder.  It's worth bearing in mind that your device may be controlled by very simple device. 

Transports

It's worth mentioning that protocols and transports are very different.  A transport could be considered to be the road that the protocol messages we send travel along.  The optimal case is that a protocol doesn't care how its messages go from A to B.  There are many great examples of manufacturers who implement a protocol that is identical whether it uses a serial (e.g. RS232, RS485, RS422) transport or uses an IP (e.g. TCP, UDP) transport.  There are equally as many examples where manufacturers introduce transport specific elements into their protocols.  Give yourselves a D-

Where multiple transports are supported, not only should it be unnecessary to confuse the transport and protocol, it allows a developer to maintain a common code base, and this improves software quality and efficiency.

The general approach that a manufacturer choses for their control protocol's transport can have a big impact on how the control implementation performs.  As I mentioned above, the choice of technology can make implementation simple or complex, but some technologies are just inherently poor choices for certain types of control.

As an example HTTP/RESTful APIs are very common.  This is likely because they are so accessible, have ubiquitous support in web applications which will likely be implemented within the device already and are generally easy to understand.  However, they are stateless and generally pretty slow.  Each request must be received, handled by the HTTP server, and passed off to the handler.  This may be fine if all you want to do is switch a device on or off, or change an input, but when it comes to tracking a volume slider in real time, they just don't cut it.

When I'm designing and implementing a control protocol I would always favour better performance at the cost of implementation effort.

If I change the input from the front panel, how do we communicate this back to the controller?  With HTTP your only solution is to poll - which is a poor solution for all sorts of reasons or use hacks like HTTP long polling - did I mention that is a hack to get around the deficiency in the HTTP request/response model?

Web Sockets might provide "best of both worlds" solution, but if you don't already have Web Socket client support, you have a lot of work to achieve a result that perhaps might been better served with a simple TCP socket.  IT requires a deeper understanding of TCP and sockets, but - to be fair - you are implementing a machine-machine interface, so that's probably worth getting a grasp of anyway.

The Protocol

There are so many ways to design a protocol, and the correct approach is really down to application.  That could mean designing a message structure that is human readable (i.e. ASCII) so that you can communicate with the device via a terminal emulator, or you might want more efficiency with a pure binary payload.  Either way, messages must be expressed in such a way that a client can easily identify where they start and stop.  Error detection may also be a requirement, though remember that TCP handles this for you, so anything else you add is pointless if you ONLY support TCP.  If you may also use serial or UDP transports, this is where some error handling will be needed. 

JSON is another popular payload.  It's human readable, it's pretty concise, fairly easy to parse and there are lots of tools to help you validate syntax etc.  It's also very easy to create some pretty freakish structures that can make deserialisation into objects an absolute nightmare.  Just because it validates, it doesn't mean it's well designed, and it's well worth adding in some additional specificity into the structure to make it unambiguous (and deserialisable!) at the expense of some extra characters - if you're really on an efficiency drive, then you're barking up the wrong tree with JSON in the first place.

Google's Protobuf is an example of a very efficient, flexible and robust message payload - the trade off is it's complicated to implement message reader/writers.

At the other end of the scale there are formats such as SOAP.  Fine if you're writing web discoverable business services.  Not really suitable for M2M communications.

Documentation

Once we have a protocol designed, implemented and tested, it's ready to be released into the world.  But not until it has been documented.

I would suggest that at the VERY least, a public protocol specification should cover the following:

• Transport details - Serial comspec (9600-8N1, hardware pinout etc.) or TCP port for communication
• The general packet structure for the payload along with any additional notes that apply to transport specifics (authentication, handshaking, heartbeats etc.)
• Complete payload documentation describing all commands, values and valid ranges - this gets forgotten so often
  • If I'm setting volume, how am I to know if the protocol expects 0-100, -90-0, 1.0-50.0?
• An example for each command, including the possible expected, and error, responses

 The reality is we may get a spreadsheet with an incomplete table of messages that do specific things, but don't explain the structure, how checksums are calculated, the allowed values (which may need to be given for specific models) and no mention of valid responses or even whether one should be expected!  Yes, it can be used to reverse engineer a protocol, but this shouldn't be part of the driver development process.

It goes without saying that documentation should also be accurate.  I recently had to request the serial comspec for a device as it wasn't mentioned in the documentation.  After waiting too long, I broke out the logic analyser, measured the time between a pulse at 8.6us and established that we were using 115200 baud.  Then I received an email from the manufacturer telling me to use 192000 baud.  Wrong on so many levels ;)

If you need help pulling your device protocols into shape so that your device is easy to integrate, performs well and is reliable, we'd be pleased to offer our help based on many years of experience.

Getting a Crestron Home Driver into Development

We regularly get contact from integrators and manufacturers about writing drivers; usually an email that looks something like this:

"We need a Crestron Home driver for the "ACME Super-Deluxe Awesomeness".  It's used by everybody in my area and it'd be amazing if we had support for this in Crestron Home.  Please let me know if you can do it and how much it will cost."

I've written the same reply to so many of these emails that it seems like a good idea to give the nuts and bolt of the answer here.  So - here we go...

The bottom line - there is no short answer here, as whether one can write an integration driver for any home automation system is partly a technical question, partly commercial, and sometimes even touches on policy for the platform.  The questions that need to be answered (in no particular order) are:

1. Does the device have an API (Application Programming Interface)?
   Fundamentally - if the "ACME Super Deluxe Awesomeness" doesn't have an integration API - i.e. there is no programmatic way of controlling the device, then you can probably guess where that leaves us.  It's true that some, very simple, devices don't need an API - perhaps they're just controlled by a simple relay - but that leads to a different question (later) and this perhaps a very small edge case, in terms of what we're talking about here.
   
   
2. Is that API publicly available?
   Many devices have APIs, but they're not all published, and sometimes they are actively kept hidden - such as in the case of Apple's MediaRemote protocol.  Using the Apple example is intentional, as we've shown that this isn't necessarily a barrier to getting a working integration module, but the point here is - it makes the task considerably harder.  This isn't related to the functions of the device either.  Something like a power distribution unit may have very simple functionality - switching an outlet on or off - but to make that happen may require complex authentication or involve encryption to avoid someone switching things on and off when they shouldn't.  Having the API/protocol documented is a key consideration here.
   
   
3. Is the API any good?
   Not all control protocols are created equal.  For every well designed, well implemented and well document protocol, there are many more that are badly designed, poorly implemented and the documentation is vague or just plain wrong.  The better the API, the easier the task of implementing it for Crestron Home.
   
   
4. What's the development effort?
   This is a function of different aspects but, primarily, how complicated the API is to implement and how much functionality is required.  APIs requiring OAuth or encryption will be more challenging than one that uses a simple ASCII CR/LF delimitered protocol.  A device that requires only requires turning on and off will be much simpler that a device that has complex audio DSP control.  We can only estimate development effort once we have visibility of the API and an unambiguous specification of what is required - but this will generally be measured in man-days of effort.
   
   These points have all been technical in nature, but that isn't the only consideration when we schedule work for a new driver.
   
   
5. Is development equipment available?
   It's been done before, but writing an integration module against documentation only is a gamble.  Inevitably, the first time you fire up a new driver you immediately find a fundamental issue with the communications.  Having equipment to test against is essential.  That doesn't necessarily mean you need a complete system - being able to test against the communications board of a display may be sufficient (as long as it can function without the glass).  Some manufacturers are happy to provide equipment which makes things much easier.  Some manufacturers aren't quite as accommodating - those manufacturers don't get a driver.
   There is a middle ground where people offer to "be the tester".  As helpful as this is, it's far less efficient than having the device in the development environment.  During a day in development, we may iterate through 20 or 30 changes and being able to debug directly, watch the low level communications and identify defects in real-time is the only way to go.  When it comes to beta-testing, then we welcome integrators who can really put a device driver through its paces.
   
   
6. Who's covering the cost?
   One way or another, we need to cover the financial cost of the development effort (and testing, any peripheral equipment, rent, power, etc.) and this is where we can take two different approaches.
   Our preferred approach is that we develop a driver, bear the cost of the development, and then recoup that investment through incremental sales over time.  For this approach to be viable, we need to be reasonably confident that the finished driver will sell in sufficient quantity to - at least - break even, and if the product is particularly niche, or the development effort is likely to be very high with only limited sales, then the driver is probably not a good candidate for our work pipeline.
   The other common option is for a manufacturer to bear the cost of development.  They naturally have a vested interest in having their device supported in Crestron Home so that would open sales opportunities that would otherwise be closed.  This then means that the module is free to use to integrators.
   The least common option is for an integrator to cover the full cost so that they can have some sort of exclusivity over a particular device to create a unique proposition for their clients.  The risk being that someone else could take a similar view and undermine that exclusivity.
   
   
7. Does it "fit"?
   This is a particular consideration for Crestron Home.  Crestron Home uses the "Crestron Certified Driver" framework for device drivers which you could look at as a driver being block of a certain shape that will only fit into the hole of the corresponding shape in Crestron Home.  So - displays have one shape, cable boxes have a different shape and some things simply don't have a shape at all.  To make things more confusing, Crestron Home does support some device types, such as lighting, HVAC or media streamers that aren't available for driver developers and have to be "baked into" the Crestron Home product.  Lutron and Sonos are examples of this.
   When we're looking at developing a driver, we can only do this for driver types that are supported, or try to be creative and fit an unsupported type into one of the supported types - for example - our NVR drivers are masquerading to look like cable boxes from Crestron Home's point of view.
   Crestron Home is expanding the list of driver types all the time, so this constraint is gradually diminishing, and we also have a special device type called "Extension Devices" which opens up the opportunities for this that can't yet be accommodated by one of the standard types, with the caveat that Crestron Home doesn't really integrate these devices other than providing simple commands in sequences and via the UI.
   
   
8. Timing?
   Sometimes the timing just isn't right.  You may need a driver for a project right now and we may be able to develop a driver quickly enough for that need; but if Crestron have already got a driver in their development pipeline and, say, it gets released shortly after, the market for the driver vanishes over night.  There's certainly something to be said for being first, but this is another angle that needs consideration.

If the answers to these items are generally positive, or if you'd like to discuss the possibility of having a driver developed for Crestron Home, then we would love to hear from you.  Just contact This email address is being protected from spambots. You need JavaScript enabled to view it.