Affected Products

Problem

During integration of Crestron Q-SYS Module Set, you may experience feedback issue coming from Q-SYS, or certain modules work while others do not. 

Causes

Many problems in achieving proper Crestron control of Q-SYS can be resolved by following some fundamental best practices and understanding some basic background of the reasons for them: 

• It has been found that it is better to delay the “Initialize” signal of the QSYS Core module by a few seconds (10-15 seconds, or more) after the start-up of the Crestron program.  Crestron’s sample program (that comes with the V4.2.1 series modules) implements that suggestion.  The module Help PDF recommends a pulse as opposed to a solid logic “high”; that may be more flexible in allowing for module re-initialization programmatically.
• While both the “Connected” and “Initialized” signals generally go "high" at the same time and maintain that status while Crestron and Q-SYS are connected, that is not always the case.  Crestron states that the “Initialized” output should drive the individual modules; that is best practice at all times.
• The “Initialize” on individual modules must be held “high”, as one portion of ensuring that an individual module gets registered by the Core module and in turn registered in a Q-SYS Change Group.
• The “Poll_Enable” signal on individual modules must be held “high” at any time that viewing feedback from a control is desired (ex. when viewing a control value on a specific UCI page, or when requiring the control value in logic).  Polling rate is defined by the Core module.  It the signal is left “low”, the module will not register as requiring feedback changes from Q-SYS.  Disabling “Poll_Enable” will remove the control from any Change Groups on Q-SYS, leaving just the outgoing control for use and all subsequent feedback within the Crestron program itself.

Solution | Workaround

The next item to look for are certain tell-tale signs in the Crestron Debugger information.  These will show up when either the Crestron program restarts (processor reboot or program restart), or the Q-SYS design is restarted (core reboot, or design push).  Some common messages:

• Null Reference Exception Error 

  Note

  This error may sometimes appear on its own due to other issues in the Q-SYS module set.  It also may show up in other modules not related to Q-SYS at all.

   
• Unterminated string.  Expected delimiter…
• Unexpected character encountered while parsing value…
• Unexpected end of content while loading JObject.
• Error reading JObject from JsonReader…

If those messages occur, it is time to find out why, and then take steps to mitigate them.  The feedback issues that result in these messages are a result of the Crestron module choking on the sometimes large JSON-RPC responses from Q-SYS.  To be clear, this is a Crestron issue, and not a Q-SYS issue.  Technically it is up to either the Crestron programmer or Crestron themselves to resolve this.  However there are ways to mitigate and even prevent the issue from occurring.

The best method to troubleshoot Crestron to Q-SYS communication issues is to grab a Wireshark PCAP capture.  A capture of TCP/IP traffic from the core to the Crestron processor, on Port 1710, is required.  From that capture it is possible to identify the location in JSON-RPC responses where the Crestron module fails.

The V4.2.1 module set will not accept anything over one TCP packet.  JSON-RPC responses can technically span multiple TCP packets.  Therein lies the issue, and also the path to mitigating the issue:

1. Keep names of Named Controls as small as practical.  The default names of Named Controls can sometimes be long.  There is no need to keep those default names.  Sometimes this step is all that is required.
2. Only add polling to the Modules (controls) you really need.  This will minimize the size of the initial JSON-RPC response from Q-SYS.
3. If polling on a sizable number of Modules (controls) is still needed, then space out the rate at which polling gets enabled.  Adding several groups of Modules (controls) over the period of 5, 10, 20 seconds or more will do much to minimize what would have been a large JSON-RPC response coming back.  Implementing this may at times take some trial-and-error to ensure that the issues have been resolved consistently.