Troubleshooting 3rd-party integration issues with HWQS
While many customers utilize the HWQS system's ability to integrate with other 3rd-party devices, any issue that occurs in the field can prove to be the most challenging to troubleshoot. While it's not impossible to determine the problem in the setup by yourself as the HomeWorks dealer, we strongly recommend working together with individuals knowledgeable on each system involved when attacking 3rd-party integration issues on-site. The logistical difficulty of arranging for everyone to be in the same room at one time can greatly outweigh the headache of an elongated, persistent issue that never seems to be nailed down by either expert alone.
- Verify 3rd-party integration setup steps
- Using the 3rd-party integration setup app note, verify each step was completed correctly to the best of your knowledge. Double-check that the correct scenario was originally considered. For example, if the HWQS system will be sending a 3rd-party command to the 3rd-party device, then either scenarios 1 or 2 would be used. If the 3rd-party system is sending Lutron commands to the HWQS system, then scenarios 3 or 4 would be used.
While each integration scenario shares certain characteristics, the best troubleshooting path differs depending on the type of integration attempting to be implemented.
Troubleshooting Inbound Integration Issues (3rd Party Device -> HWQS)
- Remove the HWQS and 3rd-party system from the network
- To eliminate the chance network devices or the network itself is preventing the ability for the 3rd-party system to Telnet into the HWQS processor, disconnect both from the network and connect a single Ethernet cable between the two devices, if possible.
- Once connected directly, ensure a static IP has been set on both devices within the same network if not already set. For example, the 3rd-party device can be set to 192.168.1.99 and the HWQS processor can be set to 192.168.1.100 to allow communication between the two devices. Re-test the 3rd-party system to see if it can now control the HWQS system while off the network.
- Verify the HWQS is programmed to accept and successfully act on a command from a 3rd-party system
- Using a computer, open a Telnet session to the HWQS processor targeted by the 3rd-party system (it may be necessary to install Telnet). Go to Start -> All Programs -> Accessories -> Command Prompt. In the prompt, type in "telnet XXX.XXX.XXX.XXX" and press Enter, where the X's are replaced by the IP address of the processor targeted by the 3rd-party system.
- If prompted for the "login:" prompt, input the username to be used by the 3rd-party system and press Enter. Once prompted for "password:" input the password assigned to the 3rd-party system.
- If Telnet returns with a message "Could not open connection to the host, on port 23: Connect failed", then check the IP address of the processor and ensure it's on the same network as your computer. Also ensure that your laptop is connected to the same network. If the processor has an IP address of 192.168.1.100 and your computer has an IP address of 192.168.2.101, they are not on the same network. The computer's IP address must be changed to 192.168.1.101.
- If Telnet returns with a first prompt other than the "login:", it is possible there is another device on the network that has been assigned the same IP address of the processor. Also, it would be best to verify the IP address of the processor in the HWQS software to ensure the correct IP address is being used.
- If after inputting the Telnet credentials, the processor returns back with "bad login", verify the username and password for the 3rd-party system has been defined in the HWQS project file. Re-transfer to the HWQS system and re-test to ensure the system is running a copy of the project with the Telnet login defined.
- Once logged in using the credentials defined for the 3rd-party system, send a command that was used by the 3rd-party system unsuccessfully to the processor.
- If the processor returns with an "~ERROR,X", the command syntax is incorrect. To help you determine the correct syntax of a command, you can request help from the processor by appending a ",?" . For example, sending "#device,?" will return the possible parameters to the command and its usage syntax ("#DEVICE,<ID>,<component number,<action>...").
- Verify the device you are attempting to integrate with has been enabled for integration. To do this in the HWQS software, go to Tools -> Configure Integration -> Integration tab. If any changes are made, it is necessary to re-transfer the project file to the HWQS system.
Troubleshooting Outbound Integration Issues (HWQS -> 3rd Party Device)
- Check outbound 3rd-party status connectivity
- One of the best ways to determine if the issue resides on Lutron-side or the 3rd-party side is to determine whether or not a command is crossing the "bridge" between the two systems and that the commands specified in the HWQS program are actually being transmitted from the HWQS processor.
- Open Terminal and connect to a processor in the system.
- Send the command "outboundconnections". This command should return a list of the outbound 3rd-party connections that particular processor is responsible for opening. If you do not see the name of the 3rd-party device in question, disconnect from the current processor, connect to the next processor in the system, and send the outboundconnections command.
- Check whether or not the HWQS processor has established a connection to the 3rd-party system.
- If "Is connected to device:" returns "Not Connected", verify the 3rd-party device IP address and login credentials. If verified, try to make a Telnet connection from your PC connected on the same network to the 3rd-party device. If unsuccessful, ensure the 3rd-party device is setup to accept Telnet connections.
- Check the command history of commands transmitted to the 3rd-party device. Ensure the command entered in the custom command set in the project file is transmitting the appropriate commands. Starting at the top, the command history is listed from oldest commands sent to most recent.
- If the expected command does not appear to be sent according to the history, verify the command is programmed in the system on the device used to test (i.e. keypad button press). When controlling multiple 3rd-party devices from the HWQS system that use the same command set, be sure that the proper 3rd-party device was programmed on the button. For example, a Front Yard Fountain Controller assigned to the keypad button labeled "Backyard Fountain ON" is incorrect.
- Attempt to Telnet into the 3rd-party system from your computer on the same network and try sending the custom command.
- If the 3rd-party system does not respond, work with the 3rd-party manufacturer to determine if there is a syntax issue, connection issue, or setting issue on the 3rd-party side that enables their system to accept commands from other devices.
- RS-232 to Ethernet adapters
- If using an RS-232 to Ethernet adapter, you can use your computer to verify the 3rd-party commands are transmitted on the RS-232 side of the adapter
- Using a null modem cable or a straight-through cable with a null modem adapter, make a serial connection between your computer and the adapter.
- Using PuTTY or another terminal program, open a terminal window to the adapter. Once opened, exercise programming on the HWQS-side that should output a 3rd-party string.
- If the string does not appear in the terminal screen, ensure your terminal program is following the baud rate/serial settings specified or configured in the adapter.
- Some terminal programs do not reveal present line feeds or carraige returns. If the command appears, double-check with the 3rd-party manufacturer to determine if an RS-232 terminator is required (carriage return or line feed) and if so, defined in the 3rd-party command set in the HWQS software.