QW Home Automation controller (QWHA Controller) is a professional Home Automation controller software. Currently the controller supports Insteon protocol based devices. More protocols will be supported in the future.



QW Home Automation is a complete software solution for home automation. It consists of the following components:

Controller Server

A server process running around clock. It acts as a bridge between your broadband internet and your home automation enabled devices such as dimmers, switches and thermostats.
QWHA controller features complicated logic engine to manage arbitrarily complex control logic.
QWHA controller is currently running natively on Windows and Linux (Raspberry Pi) platforms.

Client Application

Android version available, other devices coming soon.


Controller Server

Controller server can be a Raspberry Pi or a Windows PC.

Insteon Protocol

Insteon PLM (or Insteon SmartLinc 2412N) is required to control Insteon based devices. Insteon PLM can be either a USB ir serial device. Both are supported.

Starting from version, support for SmartLinc 2412N is added. SmartLinc is designed as a standalone controller. However it offers very limited features. QWHA will use SmartLinc as a network based PLM based on undocumented TCP port 9761.



For Windows installation, download the Windows version of QWHA Controller from the download section. Execute the setup.exe and follow the instructions.

The installer will also change the firewall settings to enable network for both the controller server and the admin processes.

Configuring QWHA Controller for the First Time

If this the first time you install the QWHA Controller on your system, you must configure it. After the installation, launch the QWHAConfig application.

  • Admin Account
    On a fresh installation, the system will automatically create an administrator account with user name "admin" and empty password.

    In case the user later forget the password, a "ResetAdmin" button is added to QWHA Config utility. Clicking that button will reset the password of user "admin" to empty. If admin account doesn't exist (e.g. the account is deleted), a new "admin" user with empty password will be added.

  • Server TCP Port
    The server needs to listen on a TCP port so that user can further configure and control your devices. Press the "Auto Generate Port" button the application will automatically choose an available port from 49151. Or user can manually specify a port.

    Note: Certain well known ports such as port 80 and 23 are blocked by most of ISP in the world. Try to avoid any port below 1024 unless you know exactly what you are doing.

  • You need to write down the TCP port. You will need this information to to configure your Cable/DSL router (port forwarding).
  • Controllers
    Currently only Insteon PLM controller is supported. Follow the steps below to add add the PLM.

Adding an Insteon PLM

First of all, make sure the PLM is plugged in the USB port and the power outlet.

Click the "Start" button of your Windows. Find the "Computer" entry on the right side of your start menu. Then right click your mouse and choose "Properties".

A "System" panel will pop up. Choose "Device Manager" on the left side as shown below.

A "Device Manager" panel will pop up. Navigate to "Ports (COM & LPT) and look for "USB Serial Port". And take a note for the port number.

Note in this example the port is COM3. However it may vary from machine to machine. The best way to identify the correct port is to keep the "Device Manager" panel open. Unplug the USB port of the PLM. The device manager should automatically detect the change and refresh the list. The corresponding port will disappear. Then plug the USB back on the panel will refresh again and the port will reappear.

Adding a SmartLinc 2412N

The SmartLinc should be in the local network with a local static IP address. The static IP address can be specified using SmartLinc web interface or setting up the "static DHCP lease" in your broadband router (if the feature is supported by the router).

Applying the Changes

Click "Apply" button, if there is any modification, the changes will be saves. The QWHAConfig tool will do the following:

  • Temporarily stop the QWHA Controller Windows Service (If it has been started)
  • Check whether or not the configuration is valid, for example (is the TCP port really available?)
  • Add an entry to "%SystemRoot%\system32\drivers\etc\hosts" to reserve the TCP port
  • Automatically restart the QWHA Controller Windows Service (only if it was started when QWHAConfig started)

Don't quite understand the above steps? Don't worry. It just says the the QWHAConfig does everything necessary for you and now your QWHA Controller should be up and running.

Raspberry Pi

Following the instruction below to install QWHA controller on a raspberry Pi:


  • Raspbian
    Please install the latest firmware of Raspbian.

    Note old firmwares released in year 2012 may have problem with FTDI driver, which is required for USB Insteon PLM.
    USB Insteon PLM is automatically supported in latest Raspbian. Simply plug in the PLM to the USB port, the USB serial port will be added.

  • Dependencies:
    Use the following script to install dependencies:
    sudo apt-get update
    sudo apt-get upgrade
    sudo apt-get install gcc-4.7 g++-4.7
    sudo apt-get install libssl-dev
    sudo apt-get install libboost1.50-all-dev
    sudo apt-get install libc-ares-dev
    sudo apt-get install psmisc
    sudo apt-get install libsqlite3-dev
    sudo apt-get install expat libexpat-dev
    sudo apt-get install ftp

Install QWHA Server

Log on to your your Raspberry Pi.

If you are upgrading from previous version, run the commands below first:

sudo service qwha stop
rm ./installqwha

Run the script below to install QWHA:

wget http://qwhomeautomation.com/raspberrypi/installqwha
chmod u+x installqwha

Upgrading To Version 1.7+

If you are upgrading from previous versions to version 1.7+, you will need to make the following changes:

If you are using a USB PLM, you need to:

cd /etc/QWHA
sudo nano config.xml

Then find


Replace the attribute with


Note you have to specify both SSLPort and AESPort. They have to be two different ports. For more information about security please read "Security".

Once you saved the new config.xml file, restart QWHA with the command below:

sudo service qwha start

Migrating Existing QWHA Settings From Windows Version

If you have been running the Windows version of QWHA. You can easily migrate the settings.

Depending on the version of your Windows,

If you are running Windows XP,look for Teraspaces\QWHA folder in C:\Documents and Settings\All Users\Teraspaces\QWHA  orC:\Documents and Settings\All Users\Application Data\Teraspaces\QWHA folders

If you are running Window Vista/7/8, it should be under C:\ProgramData\Teraspaces\QWHA

Just move the content of the entire folder to the /etc/QWHA folder

If you are using a USB PLM, you need to:

cd /etc/QWHA
sudo nano config.xml

Then find

<SerialPort COM="......">

Replace it with

<SerialPort COM="/dev/ttyUSB0">

Also add a new attribute to <Config> element:


Such as

<Config GUID="" SSLPort="65001" AESPort="65002" WebPort="8080" WebRoot="/opt/qwha/web" InsteonStatLogInt="15" LogPLM="0" Version="" >

New QWHA Installation

cd /etc
sudo mkdir QWHA
cd /etc/QWHA
sudo nano config.xml

Then copy the following XML to the editor:

<?xml version="1.0" encoding="UTF-8" ?>
<Config GUID="" SSLPort="65001" AESPort="65002" WebPort="8080" WebRoot="/opt/qwha/web" InsteonStatLogInt="15" LogPLM="0" Version="">
    <SerialPort COM="/dev/ttyUSB0" Device="InsteonPLM" DeviceID="XXXXXX" />

Feel free to customize your own SSLPort, AESPort and WebPort.
Note, you need to reset the AdminPassword, and replace the DeviceID of "XXXXXX" with the actual ID of your USB PLM (found at the back of the modem).

For 2412N, Replace this:
    <SerialPort COM="/dev/ttyUSB0" Device="InsteonPLM" DeviceID="XXXXXX" />
    <InsteonSmartLinc2412N Host="xxx.xxx.x.xx" Port="9761" DeviceID="?" />
Note: you need to fill in the IP and Insteon ID of your 2412N in the config above.

Setting Up Service

You can create a service to let QWHA automatically run at startup.

cd /etc/init.d
sudo wget http://qwhomeautomation.com/raspberrypi/qwha
sudo chown root:root qwha
sudo chmod 755 qwha
sudo update-rc.d qwha defaults
sudo update-rc.d qwha enable

QWHA can be started or stopped by the following commands:

sudo service qwha start
sudo service qwha stop

Reset Admin Password

On a fresh installation, the system will automatically create an administrator account with user name "admin" and empty password.

In case the user later forget the password, use the following command to reset it.

sudo service qwha stop
cd /opt/qwha
sudo ./qwhaserver resetadmin
sudo service qwha start

It will reset the password of user "admin" to empty. If admin account doesn't exist (e.g. the account is deleted), a new "admin" user with empty password will be added.

Further Configuration of Your Home Network

You may need to further configure your home network so that you can remotely access you QWHA Controller from anywhere in the world through internet. It can be achieved by the following steps:

  • Assigning an internal static IP to your QWHA Controller.
  • Opening an "NAT Port Forwarding" in your main Cable/DSL router/firewall
  • Setup a "Dynamic DNS" for your broadband connection

Basically those are just configuration changes on your Cable/DSL router and should NOT cost anything. These steps may get too technical and may vary for different type of devices and ISP. Users can use our "Forum" to discuss those issues.

QWHA Controller Administration

QWHA Controller Administrator's tool (QWHA Admin) is a web based tool. User can use any modern web browser to remotely connect to the controller to launch the admin tool.

Launching QWHA Admin

In the web browser address bar, type the URL of the controller. Note for security reason the QWHA controller only supports secure HTTP connection. The URL must starts with "https" instead of "http".

The general format of the URL should use the pattern below:

For example, if the controller address is, and web port of the server is 65001, then the URL should be:


The Admin GUI has two parts. the left side is the Navigation panel, the right side is the panel area.

Clicking the line item in the navigation panel will open the corresponding panel in the panel area.

Panel area has tabs on top. Multiple panels can be opened. Use the tabs on the top to navigation through opened panels.

There is a "Close Icon" on each tab. Clicking the 'Close Icon" will close the tab.

Apart from the panels, some features may use dialog or Wizard dialog, as shown in the screenshot above.

Running QWHA Admin for the First Time

The first time the user launches the QWHA Admin on a freshly installed controller, the user is is required to give some information about the user's home.

Latitude and Longitude

Latitude and Longitude are required to calculate the position of the sun. Several functionality of QWHA depends on that information. For example, the system is able to tell if it is day time of night time by comparing the current time against today's sunrise time and sunset time.

User can get the latitude and longitude from https://maps.google.com/.

First, navigate to you residence.

Then right click the mouse on the spot you want to get coordinates.

A popup menu will show up. Choose :What's here?".

An arrow icon will be pinned on the location. Click the icon to get the coordinate.

Time Zone

user is required to specify the time zone of the location. Just select the time zone from the drop down menu.

App Store Login and Password

User need to set up app store credentials in order to use the app store.

Developer Settings

Users can developer Applications for the controller. In order to use the built in development tools, user must become a developer by "enabling the development mode".

User also needs to register a developer name on the App store.

Open Weather Map App ID

If user wants to use any App that uses Open Weather Map as weather service, user is required to apply an App ID (for free) from OpenWeatherMap website.

Change Settings Again

If in the future the settings change. For example, the user may move to a new location so the latitude and longitude or time zone may be changed. In that case, user can change the information again by nagivating to "Controller" -> "Settings" from the navigation panel on the left side of the screen.

Managing Insteon Devices

Insteon Devices Panel

From the left side navigation panel, navigate to "Controller"->"Insteon"->"Devices" to open the device panel.

The Insteon Devices panel has two sub-panels. The "Devices" sub-panel and "Device ALDB" sub-panel.

In this example, the device "CentralHall" is all-linked the PLM, as well as three other switches. In the "Device ALDB" sub panel, each linked device has a "DeviceRole" column, which is the actual role of the selected device against the linked device. The selected device "CentralHall" "controls" the PLM. When user turns the switch on and off, the PLM received the control signal. Also, "CentralHall" "IsControlledBy" 3 other switches. The four switches forms a "4 way switch". The same load is controlled by 4 switches, where only one switch has the actual load and 3 other switches only sends the signal to the load switch.

Devices Sub-panel

Devices Panel lists all "detected" devices in the system. A device is detected means that the PLM has successfully communicated with the device, got the type of the device and downloaded the All-Linking database from the device into the system.

User can perform the following operations on the devices:

Managing Device Names

Each device should be given an unique name across the network. User can choose any name for a device as long the length of name is not too long (should be less than 128 characters).

The name should be concise and intuitive, for example, name "2ndFloorHall" may be used for a light in the hall of second floor.

At the time the device is initially added, the device has no name. A "? not set" will appear in the name field. User should change the name by double-clicking on the name field and edit the name in place. Once the user finished editing the name, user should press "enter" key or click mouse outside the name field to save the new name.

The device name has to be unique across the system. If the name conflict with another name, the name will not be saved. An "exclaim" sign will appear in the name field to indicate an error.

User can change the name of a device at any time. Once the name is changed, the name of the device referenced in other UI will be changed automatically.

Add Logical Device

For example, I have a RemoteLinc that has 6 bbuttons with a name of "MasterBRRemote(Mrs)".

It is a 6 button remote. Each button can be treated as a logical device. In this case we add a button 4, and give it a MasterBRRemote_Button4.

The old version of the Insteon remote has buttons to control all linked devices. For example, in the remote showned below, the buttons in lower part can be used to send "All On", "All Off", "Dim All Up, or "Dim All Down" signals. Those buttons has special All-linking group number of "255".

Delete Device

This button will permanently remove the device from your home. If the device is already linked to other devices, the system will try to remove links from other devices automatically.

The first step is dependency checking. Dependency checking may generate a warning which require user's explicit confirmation to proceed. For example, if the device is referenced in a scene or timer, upon user's confirmation, the associated action will be deleted from action list automatically. Dependency checking may however generate an error. For example, the device may be referenced by an App Engine Task. Because the device may be part of a complex input structure, it may be quite complicated to recreate the entire task. In this case an error will be thrown so that user can take manual action to resolve the problem.

If some devices are battery powered. The device should be waked up first; otherwise the operation may fail partially because the all-linking information can't be written.

Add New Device

If you have a device that is curently not managed by QWHA Admin and you know the address (Insteon ID) of that device, you can use this button to add the new device to the system. Once the button is clicked, a dialog will pop up asking for the Insteon ID.


If the selected device is already linked to some other devices that the system is not known yet. User can instruct the system to perform "automatic discovery" process by querying the device type and all-linking information. It usually happens after a new device is added to the system.

Note: If the device is a battery powered device, wake up the device by pressing any button immediately before pressing the delete button; otherwise the device will not respond.

Advanced Configuration

This is the advanced configuration for many Insteon devices.

It is useful for devices such as KeypadLinc, IOLinc, RemoteLinc, SwitchLinc, Motion Sensor etc.

Depending on the firmware version of the device (could be 0, 1 or 2), QWHA may use Insteon commands, or memory map operation, or both to perform the setup.

For more information, please refer to Insteon Advanced Configuration.

Device ALDB Sub-panel

The "Device ALDB" sub-panel lets helps user manage the device linking among Insteon devices. The panel contains a table that lists all linked devices against the currently selected device in "Devices" sub-panel.

The sub-panel has a toolbar with the following functions:


In the above example, we added a logical device, which a button on the remote "MasterBRRemote(Mr)", with the name "masterBRRemote_Button4".

This time we link this button to a light "2ndFloorHall" so that user can use this button to turn the linked light on and off.

As a rule of thumb, every logical device should be All-Linked to PLM, so that the PLM is able to receive every control signal and keep the latest state of the device without polling the device.

All-Link information will be remotely written to both devices.

In-depth discussion will be covered in "advanced topics".

Note: If the device is a battery powered device, wake up the device by pressing any button immediately before pressing the delete button; otherwise the device will not respond.


This button will delete the selected All-Link entry from devices (both the controller and the responder).

Note: If the device is a battery powered device, wake up the device by pressing any button immediately before pressing the delete button; otherwise the device will not respond.

Refresh ALDB

Press this button will refresh the All-Link information of the selected device. For example, if you set up the all-link manually using the "set button" of the device, the QWHA system won't know the change. Pressing this button will force the system re-synchronize from the selected device.

Note: If the device is a battery powered device, wake up the device by pressing any button on the device immediately before pressing the refresh button; otherwise the device will not respond.


Edit additional properties of the selected link. The behavior depends on the type of the linked device.

If the device is a dimmer, and the dimmer is acting as a responder (being controlled), user can use this button to adjust the on level and ramp rate.

On-level ranges from 0 to 255. Ramp rate is the time between full off to all on. Default is 0.1 second.


If the selected entry represents a device not added in system yet. Use this button to query the device and automatically add it to the ssytem.

Final Note: Be patient!

Note: The Insteon network is running at a very low data rate. Some of the operations may result in fairly big amount of communication within the network and take minutes to finish. Please be patient and do NOT shut down and part of the system during the process.

PLM Panel

In the left side navigation panel, navigate to the PLM node. PLM panel will be brought up.

PLM panel lists all devices in the PLM all link database.

Note, after the intial setup. The devices may not been identified or given a name yet. Only the device type will show up.

User can perform the following operations on PLM by pressing buttons on the tool bar on top:

  • Add New Device
    Pressing this button will put the PLM in all linking mode. PLM may act as either a controller or responder, depending on the all-linking sequence.
    Once the PLM is in all linking mode, you have about 4 minutes to complete the all-linking process. Refer to user manual for specific Insteon devices about how to set up all-ainking using the "Set Button".
  • Remove
    Remove the entry from the system.
    Note: If the device is linked to other devices, the entries of this device will be deleted from other devices as well. Only use this feature if you want to permanently remove the device from your home.

    Note: If the device is a battery powered device, wake up the device by pressing any button immediately before pressing the remove button; otherwise the device may not respond.

  • Explore
    If the device is not yet initialized, this button will be enabled. After user press this button the PLM will try to contact the device, finding out it's type and download the all-linking database from the device.

    Note: If the device is a battery powered device, wake up the device by pressing any button immediately before pressing the Explore button; otherwise the device may not respond.

Note user cannot rename a device from this panel. To rename a device please use the "Logical Devices" panel.

Logical Devices

Logical Devices is a concept introduced by QWHA Controller. The concept of logical device can be applied to almost all home automation technologies and protocols.

In order to understand the concept of logical device, let's take a look at the Insteon KeypadLinc.
This KeypadLinc has 6 buttons. The top and bottom buttons are assigned to turn or dim the local load. The remaining 4 buttons can be customized to be linked other Insteon devices.
According to Insteon, a 6 buttons KeypadLinc has 5 logical devices, with group number from 1 to 5.
In QWHA Admin, 5 logical devices can be created out of this KeypadLinc. User can assign any name to each logical device as long as the name is unique.
The concept of logical device is even clearer in protocols such as Zigbee. In Zigbee lighting devices, even switch and light are separate logical devices (called endpoints in Zigbee). A simplest Zigbee light switch may have 1 switch and 1 light, assuming the switch does has capability to control load. In that case the switch should always be linked to the light.
Another example is multi-button Insteon remote controller. Each button on the remote controller is a logical device.

For simple Insteon devices such as regular dimmers or switches, the parent device and the logical device are treated as the same device, with a group number of "-1".

For more complex multiple button devices such as KeypadLinc, the parent device will be marked as an Insteon logical device with group of "-1", in order to distinguish from the actual logical device.

The multi-button parent device cannot be directly controlled since only the underlying logical devices can be controlled or send control signals.

QWHA Admin will automatically get all available devices intelligently so user doesn't have to worry about the difference between logical device and host device.

Logical Devices Panel

From the left side Navigation Panel, click the "Logical Devices" node to open "Logical Devices Panel".

The table lists all available logical devices in the system. Each logical device has a unique name. Note there is a "Parent" column that shows the host device of the logical device.

For example, in the screenshot, the "Foyer" is a host device ("LogicalType" column is "MultiHost"). It has 5 logical devices, the switch that controls the local load ("FoyerLoad") and 4 extra buttons ("FoyerA","FoyerB", "FoyerC", "FoyerD"). And "Foyer" is a 6 button KeypadLinc.

The right part of the "Logical Devices" panel is a properties window. For Insteon device it only displays the Insteon Device ID and Insteon group number.

Managing Device Names

User can change the devie name at any time. Simply double click the name field of a logical device, then user can edit the name in place.

Note each logical device must have a non-empty unique name. If there is a name conflict, the new name will not be saved. And an exclaimation sign will appear in the name field to indicate an error.

Load Devices

Not all devices are equal. Imagine a multi-way light. Only one switch is attached to the actual load. Other switches only sends signals to the load device when user presses the button. Of course, the system should also send the appropriate command to each switch in the multi-way switch configuration so that when the load is turned on/off (or dimmed to a new level), all linked switch get the notification. Some switch/dimmers has LED indicators that shows the on/off state or dimming level. The LED indicators will change to reflect the load state change.

Load Device and Insteon

An Insteon switch doesn't know if it is attached to an actual load, or is just a dummy switch in a "multi-way" configuration. An Insteon switch may be use as an on/off switch to remotely control other devices. In that case the switch may not have an local load.

There is no way to programmatically tell whether an Insteon switch/dimmer has local load. So user has to manually specify which switch has local load. So Insteon products has to be treated specially.

Insteon Load Panel

User uses the Insteon Load Panel to manage the Insteon load devices.

User can manual add a logical device as a load device. user can also manually remove a load device.

User can also edit the load device name in-place by double clicking mouse on the name field. Once the name of the load device is changed, the name of the logical device is also changed.

Right side of the panel is a properties panel that displays more information about the load device.

In the screenshot below, we can see the "FoyerLoad" device is a load device with Insteon group number of "1", which is the local load of a 6 button KeypadLinc.

Add and Remove Insteon Load Devices

To add an Insteon load device, click the "Add" button from the toolbar. User will be promoted with all available logical devices. Note if a logical device has already been added a a load device, it won't appear in the list of devices in the "Add Load" dialog.

Note, the "Deterministic State" flag should always be checked. generally there is no reason to uncheck it.

Whether or not a device is a load device may affect the behavior in other management features. For example, programmatically turning a light load will also change the state of all associated "non-load" switches as long as the switch is configured to control the load device. However, parametrically turning a non-load light switch will not affect the state other devices.

In the App Engine, if an Insteon light switch is a load device, it will be treated as a "light"; if it is not a load device, it will be treated as a "switch".

Software Scenes

Software scene defines a sequence of actions. The scene can be linked to a button on a mobile front-end UI. once the scene is triggered, the list of actions will be triggered all together.

Software scene can also be triggered by an App Task.

Screenshot below is the software scene panel.

Adding Software Scene

Click the "Add Scene" button, a new scene will be added to the table view. The new scene will automatically be named as "NewScene", or "NewScene1", "NewScene2" etc as long as the name is unque. User is required to give the new scene a meaningful name once it is created.

The scene name can always be changed by clicking the name field on the table.

Managing Scene Actions

User can add an action, delete an action from list, or edit existing actions, by pressing the buttons in the "Scene Actions" toolbar.

Add Action

Once the "Add Button" is clicked, a wizard dialog will pop up.

If "Load Device" or "Logical Device" is selected, user will be prompted to select a device in the next page.

In the previous chapter we discussed difference between load and non-load devices.

Depending on the type of scene and type of devices selected, user can customize the details of the action.

For dimmers, user can customize the dim level and ramp rate. Dim level ranges from 0 to 255, where 0 is fully off and 255 is fully on.

For thermostats, user can customize the mode and heat/cool setpoints.

User can even add an action to write an entry to the system log, with customized message.

An scene action can be another scene. User is responsible for not creating scene actions with circular references.

Click the screenshot below to view the screenshot in original size.

Remove/Edit Scene Action

User can remove a scene action from a scene from the UI. Just select the sction in the list and click "Remove" button on the toolbar.

A scene action may be automatically removed if the associated device is removed from the system. For example, an Insteon device removed from the "Insteon Devices" panel will automatically remove all scene actions associated with the device.

User can also edit existing actions.

Scene Action Details

the system automatically generate the user friendly "details" for each scene action.

In the screenshot above, The Scene "Test3" has two actions:

  • Turn off [Foyer#B]
    This action will turn off the back light of LED indicator of the button "Foyer#B".
  • Thermostat [Thermostat(1st Floor)] [Heat] HeatSetPoint=70
    This action will set the "Thermostat (1st Floor)" to "Heat" mode. HeatSetPoint is 70°F. When the room temperature drops below 70°F, the heat will be turned on by thermostat.


Timers can be used to schedule time dependent jobs. The screenshot below is Timers panel.

The Timers panel has two sub-panels. The upper sub-panel lists all system times. The lower panel lists actions. A timer may have two set of actions "Start Actions" and 'Stop Actions". We will discuss the actions in the next paragraphs.

Types of Timer

QWHA controller supprts several different types of timers.

  • Daily Timer

    A daily timer has a start time and stop time.

    In the settings above, every weekday at 9:00AM, the "StartActions" will be triggered, after 5:00PM, the "StopActions" will be triggered.

    A daily timer can be "inverse". In that case the "Start Time" will be later than "Stop Time", for example, start in the afternoon and stop in the morning.

    For "inverse" daily timer, the "StopActions" will be triggered on the "Stop Time" in the next day

    Note the weekday settings always apply to "Start Time". For example, if an "inverse" timer is scheduled from Monday to Friday, the "Stop Actions" will be triggered on Saturday on the "Stop Time", although Saturday in not selected.

  • Interval Timer

    Interval timer is a repeat timer. Once enabled, the system will repeat the actions periodically.

    The system will first trigger "StartActions", wait for seconds specified in "OnEvery", then start "StopActions", then wait for seconds specified in "Wait". After that the timer will automatically repeat itself again by invoking "StartActions" again.

  • Solar Timer

    A solar timer is based on the "Sunrise" and "Sunset" time, plus an offset minutes, which can be negative.

    The sunrise and sunset time depends on the geographical location (latitude & longitude), and the current date, and your timezone.

    If the solar timer is used to automatically turn on lights at night, it will be "inverse" because the start time is always later than the stop time.
    Read "inverse daily timer" for more details.

  • Countdown Timer

    A countdown timer has one parameter, a value in seconds. After the countdown timer is started, it will wait for the number of seconds specified, then the actions in the "StopActions" will be triggered.

    Countdown timer doesn't support "StartActions". It can only be triggered in control scripts or "Triggers".

    Countdown timer currently cannot be use anywhere in the system. Most likely the countdown timer will be deprecated in the next version and will be replaced with a simple built-in App.

Managing Timer Actions

Timer actions are managed in the same way as the scene actions. User can Add, Remove or Edit scene actions in "Start Actions" or "Stop Actions" list.

Timer Example

An example timer in the screenshot above, "Outdoor Lights", is a solar timer.

The timer starts at the sunset. Start Actions will be triggered. In this case, it only turns on the "FrontDoor" light.

Timer stops at sunrise. Stop Actions will be triggered. The "Stop Actions" actually turns 4 lights. Basically the timer turns off all outdoor lights at the subrise to save electricity.

App Engine

New QWHA Controller incorporates state-of-the-art App Engine that works with online App Store. The controller also comes with a full fledged development environment.

For more information please refer to:

Application Engine User Manual

Application Engine Developer's Manual

Frontend UI

UI editor is used to build a UI that will be presented on a portable device. For example, on Android phone.

UI is currently a tree structure, with three type of nodes, group, load devices and scene.

A group may contain other groups and load devices, sensor devices and scenes. It is like a folder in file system.

With the tool bar buttons user can create group, load devices, sensor devices and scenes, or delete nodes or move nodes up and down.

UI Panel

The layout of the UI panel is shown as screenshot below:

The left part is a sub-panel, which is then splitted vertically into two sub-panels:

  • UI List
    This sub-panel lists all available system UI. User can use toolbar buttons on top of this panel to Add a new UI, Remove existing UI or Edit existing UI.
  • Properties Panel
    This sub-panel helps user to manage extra properties of the selected UI node in the UI editor (right side of the UI panel).
    Details about properties will be discussed in later paragraphs.

Editing UI

Administrator can open UI for editing by double clicking the item in the UI list. Once the UI is opened, a page with tree structure of the UI will be opened in the editor panel on the right.

User can edit the nodes in the UI tree using the buttons on the toolbar on top.

UI Node Properties

A UI node may support additional properties:

  • Reverse Feedback
    If a node has this property set (as true), the signal from the device will be reversed. For example, if the frontend received an "Off" status from the controller, the frontend will display the device as in "On" state.
  • Reverse Control
    If a node has this property set (as true), the signal from the frontend will be reversed. For example, if the user turns on the device from the frontend, the frontend will send "Off" signal to controller.
  • OnText and OffText
    Those two properties override the display text for the device. For example, the default text for a switch are "On" and "Off". If the switch is used to control a garage door, it is better to override the text into "Open" and "Close".

An example properties can be found in the screenshot of UI Panel.

UI Localization

Starting from version, QWHA offers full client side localization support.

What is Localized?

Everything! From the text such as "On"/"Off" or "Heat"/"Cool", to system messages and error messages.

Multiple Localization Support on Android Devices

QWHA localization is very flexible.

  • Different language than the default language settings of the android device. For example, on an android device with default language set to "English", user can use a Chinese UI that displays every information in Chinese.
  • Multiple UI in different languages. User can user QWHA Admin to create multiple UI in multiple different languages. The user on the client can choose which UI of which language to install.
  • Extremely easy to set up. Specifying UI only takes a few mouse clicks in QWHA Admin.

Creating Localized UI in QWHA Admin

It is extremely easy to create a localized UI. As illustrated in the screenshot below, navigate to the root of the UI in UI editor sub-panel (right side panel), then add a property from the properties sub-panel (located on the lower left part).

The example below is an UI in Chinese language.

Is My Language Supported?

Any labguage can be supported. Currently, support for five languages has been built natively in the Android front-end, English, Chinese, Spanish, italian and Catalan.

It only takes you a few minutes to help QWHA adding support of your native language.

All you need to do is to download the resource file, translate it and send back to QWHA developer. Support of your language will be added in the next release.

The entire file looks like this:

Download the file from this link: (Note: In your browser, right click the link with mouse, then choose "Save Link as").


User Manager

The admin user name and password works for both the QWHA Admin and the front-end hand held devices. In addition, more users can be created only for hand held devices.

For security reasons, it is recommended that the administrator creates another user ID for himself. As a rule of thumb, any user associated with the mobile front-end shall NOT have administrator's priviledge.

The screenshot for User panel is displayed below. Administrator can add and remove users. the "Edit" button can be used to reset user password.

System Log Viewer

The QWHA Admin tool has system log viewer. Navigate to "Logs" from the Navigation panel will open the "Logs Panel".

Log Panel

The "Logs panel" has two parts. Left side is a list of all available system logs. Right part is the currently opened logs.

The log file name is the date the log file was created. There can be at most one log file per day. If the controller server is restarted during the day, the log entries will be appended.

The file name with a "*" appended is the current log file. In the example screenshot, the log file is "20150619*". QWHA Admin loads the log entries on a on-demand basis from the controller. If the current system log is open, the log entries can be tracked in real time. It can be observed that new entries are appended to the list from time to time.

Reading System Log

Logs are useful. System logs can be use for:

  • Security Log
    Everytime a user logged in, the user name and source IP:port were logged. The log can be use to track security breach.
  • Device Trouble Shooting
    Details about device problems are written into the log.
  • Application Debugging
    Application can write message to system log in order to debug the Application in real time.

QWHA Controller Advanced Setup

In this chapter we discuss some advanced topics.

Insteon Linking and Device Status Feedback

The Problem

Insteon device set up can be extremely versatile yet complicated.

For example, even without a controller, individual Insteon devices can be linked together to create fairly complicated "scenes", through a process called all-linking.

In this article, we will discuss the Insteon all-linking and how QW Home Automation will help configuration and enhance functionality.

3-Way Dimmer/Switch

The simpliest configuration is probably the 3-way switches, in which two switches (or dimmers) can both control the same load.

3-way configuration can be achieved using traditional switches. In that case flipping either switch will actually connect or cut off the physical electrical circuit to the load.

Insteon 3-way configuration, however, is different. Only one switch is controlling the actual load. The other one, is a "dummy" switch that only sends the singal to the master switch. The "dymmy" switch can even be programmed to control other loads in the future.

Status Feedback

One advantage of the Insteon 3-way switch is that both switches can be all-linked to each other. And both switches will be able to correctly relect the status of the load.

Full Cross Link Pitfalls

The disadvantage of the cross-allinking is that the number of cross all-links increases as the number of switches increases.

For example, if two switches control one single load, we need 2 total all-linking.

If three switches control one single load, we need 3 X 2 = 6 total all-linkings.

If four switches control one single load, we need 4 X 3 = 12 total all-linkings.

In my house I have one light that is controlled by 4 switches.

The complete cross all-linking not only is complicated to set up, but also introduces other issues.

First of all, user input will create a burst of Insteon message flooding. Since the all-linking record of the actual load may not be the first one, if the initial broadcast message didn't reach the load for whatever reason, the following "All-Link Clean Up" may have a higher chance to get lost in a swamp of message burst. The result will be increased unliability and/or longer response time.

One-way Linking

There is another way to set up all-linking. We can only set up all-linking from controller devices to load device. For example if we have 4 switches that control one load, switches 1, 2, 3, 4.

Only switch 1 has load.

We can only set up one-way all-linking as following:

Switch 2 controls Switch 1;
Switch 3 controls Switch 1;
Switch 4 controls Switch 1;

So instead of setting 12 links, we only need to set up 3.

The system will work correctly in response to the user control input. The only problem is that the status led on some switches may not correctly reflect the current status of the load.

QWHA Linking Status Update

QWHA will automatically infer the cross all-linking relationship based on the one-way all-linking information.

For example, in the one-way all-linking exmaple above, if QWHA controller is active, it will be able to automatically update the status led of all 4 switches in response to the load sttaus change.


In order for QWHA to support automatic status update, the following requirement has to be met:

  • Each controller has to be all-linked to PLM as controller.
    For example, in the one-way all-linking example above, the following all-links has to be set up:
    Switches 1 controls PLM
    Switches 2 controls PLM
    Switches 3 controls PLM
    Switches 4 controls PLM
  • For KeypadLinc, or remote linc, each button has to be linked to PLM as controller
  • For KeypadLinc, PLM needs to be linked to each button as controller
    For example, for an 6 button KPL, the following all-linking should be set up:
    PLM:254 controls button 3
    PLM:253 controls button 4
    PLM:252 controls button 5
    PLM:251 controls button 6
    Note in above example we use group 254, 253, 252, and 251 for PLM. Actually any group number can be used, as long as the group number is unique to any single KPL.
    The group numbers can be reused for different KPL.
  • For IOLinc, PLM needs to be linked to IOLinc as controller (QWHA uses group 254 by default).

More QWHA Magics

In memory map editor, QWHA provides a GUI tool to configure KeypadLinc buttons and IOLinc settings.

QWHA will further make use of those information to automatically control status LEDs.

For example, if a KPL button is configured as "non-toggle" button, which is "toggle" by default, and the button is configured to only send "off" command. If the linked device is turned off, QWHA will be able to automatically turn on the LED. It appears to be the unique feature only provided by QWHA.

The same is true of IOLinc, if IOLinc is configured to reverse the command for "sensor" signals, QWHA will be able to use that information to change the status LED of linked devices.

One example of the combined effect is to link two buttons on KeypadLinc and IOLinc garage door opener. One button on KPL sends on signal and one sends off signal. And the LEDs on both buttons will indicate the current status of the garage door. QWHA is able to greatly simplify the set up and correctly control the system.

Delay Feedback

Usually in a multi-way switch setup, each switch should be placed with relatively long distance away from each other, for example, controlling same ligh from different floor.

In QWHA, once one switch is pressed, the load will respond immediately. If it is not the load switch, the controller switch has hard all-linking to load switch anyway. However, the other switches' status LEDs may be updated with a delay, usually about 2 seconds.

There are several reason for that. First of all, it takes a while for the all-linking messages resulted from user action to propagate. So if the PLM react immediately the reliability will be significantly reduced.

Secondly, if the user keeps turn on and off the switch with extremely speed, the QWHA controller is smart enough to cancel out previous actions and only update to the latest status. Users can simply give it a try. No matter how you abuse the system it will always stick to the latest state on the best effort basis and the message flood wil be reduced to the minimum possible level.

Insteon Advanced Configuration

Some Insteon devices can be further customized through memory map (version 1) or special messages (version 2+). QWHA Admin offers GUI based tool to perform those customizations.

Advanced Setup GUI

From the "Insteon Devices" panel, select the device you want to setup. If the device supports advanced options, the "Advanced Configuration" button from the toolbar will be enabled. Click this button will bring up the dialog.

Admin tool will try to communicate with the device to get the current configuration. It may take some time because the bit rate of Insteon is low. Because sometimes the amount of communication is relatively high and Insteon reliability is not very good, this process may fail. in case of a communication failure, user can retry again.

Dimmer Configuration

The example screen is the GUI to further customize a dimmer. It is pretty self-explanatory.

Insteon KeypadLinc

KeypadLinc shares some common properties with other Insteon dimmers/switches, such as ramp rate (for dimmers), X10 house/unit code etc. Those properties can be modified with the editor.

Configure KeypadLinc Buttons

QWHA offers unique feature to configure buttons of KPL. Just select "KPL" item and click the button on the right, the button editor will pop up.

The button editor can be used to control button behaviour. For example, by default the KPL buttons are toggle buttons (for 6 button KPL the button 1 and 2 can't be modified, those two buttons are non-toggle that control the load), but we can modify that behaviour by setting up the follow map.

Follow On and Follow Off

We can set one or more buttons to follow the "on" state of a specified button. When the specified button is turned on, the following buttons will be on as well.

"Follow off" mean that if the specified button is turned on, the folowing buttons will be turned off. It is usually used with "toggle mode" or radio button set up.

Toggle and Non-toggle

By default the buttons are in non-toggle mode. By making the button "toggle" it will be turned on when pressed and stay on when pressed again.

For KPLs with i2 engine, a toggle button has to be specified to only send one type of command, either on or off.

Setting Up Follow Map

It's very simple, just select the "Current Mode" to "Set Follow On" or "Set Follow Off".

Use left mouse button to select the current button. Use right button to select following buttons. Note, more than one following buttons can be selected.

Current button will be market with red rectangle and folowing buttons will be marked with green rectangles.

Note: The button 1 and 2 for 6 button KPL and button 1 of 8 button KPL can't be modified because they are used to control the local load. They may not be correctly simulated either.

Test / Simulate Mode

In test / simulate mode, the user can use mouse left button to test the button behaviour, based on the follow on/off set up.

Button Status LED Update

QWHA can intelligently update the KPL button status LED based on the all-linking information and button following maps. For more information please read "Insteon Linking and Device Status Feedback".

KPL with IOLinc Garage Door Opener

It's easy to configure KPL with IOLinc garage door openers. The recommended configuration is to use two buttons to control open and close as well as LED status feedback.

IOLinc Garage Door with KeypadLinc

QWHA offers perfect solution to your garage door control with I/O Linc combined with KeypadLinc


We would want to achieve the following with QWHA garage door control.

  • We need to use two buttons to control the garage door, one button is for open only and one button is for close only
  • The garage door should have a feedback sensor to show the door open/close status and be able to send notification when the status changes
  • The door sensor feedback should be able to be reflected on the status LED of the open/close control buttons

QWHA Garage Door Solution

Here we give an example of using the following components to control the garage door:

  • An I/O Linc Garage Door Control & Status Kit from Smarthome
  • A KeypadLinc, a 6 button KPL can be perfectly configured to control two garage doors
  • Latest version of QWHA suite


Users don't have all components currently at hand may consider the following:

  • If you only have I/O Linc without the door sensor, you can still use the I/O Linc and get a door sensor from ebay. This is what I've bought:
    It's $9.95, a little bit cheaper than Smarthome's offer. Only problem is that it is "Normally Open" while the Smarthome one is usually used as "Normally Close". It can still be use and the only problem is that we have to reverse the On/Off signal to control the door, which is not a problem at all with QWHA.
  • If you don't have a KeypadLinc, you can use any Insteon relay. The configuration is a little bit different but the general idea is the same and it is very easy to figure out.

Our Example

In this example, we show how to set up the left side two buttons of a 6 button KeypadLinc to control our garage door.

The upper button will control "Open" and the lower button will control "Close".

Set up the component:

Follow the instruction to install I/O Linc and the door sensor (magnetic contact). I find it easier to use the glue to fix the sensor on the concrete floor and use screw to fix the Magnet on the wood door.

Add the I/O Linc to the System

Add the I/O Linc device to the system using QWHA Admin. Give it a name. Then add it as a "Load & Sensor Device".

Configure I/O Linc

Using Insteon Advanced Configuration dialog, configure the IOLinc as shown below:

For more information, please read Insteon Advanced Configuration

Set up the KeypadLinc

Add the KaypadLinc. Add the buttons as the "Logical Devices", and cross link every botton with PLM (as both master and slave). For more detail refer to "Insteon KeypadLinc".

In the InsteonDevices Panel, highlight the KeypadLinc device, then click the "Advanced Configuration" button on toolbar.

Then customize the KPL buttons as shown below:

In the KPL buttons dialog, use the "Set Follow Off" mode. And change the following:

  • Make sure Button A and C are both "Non-toggle" mode. (Default are both toggle)
  • Make sure Button A sends "On" and Button C sends "Off" in non-toggle mode.
  • Make sure C is Off when A is On, and vice versa.
    In " Set Follow Off" mode, left click button A and right click button C to set C off follows A on.
    In " Set Follow Off" mode, left click button C and right click button A to set A off follows C on.

Set Up All-Linking

All link both button A and C as master to control I/O Linc

All link PLM as master to I/O Linc (can use default group of 254). All link I/O Linc as master to PLM as well.

Change UI Text

By default, on the UI, the buttons for switches will show "On" and "Off". We can change it to "Open" and "Close" by changing the UI properties.

For more detail see the example below "Using the Third Party Sensors". Note for kit purchased from Smarthome you don't need to reverse the signals and control.

Now You are All Set

When garage door is closed, pressing button C "Close button" has no effect. Likewise, pressing button A when door is open has no effect either.

When door is closed, LED on C is on and LED on A is off and vice versa.

The status of door will be updated correctly on all devices (KPL, Web interface or Android client) no matter where the control signal comes from.

You can still use your existing remotes that has no link to Insteon network and the status will update correctly on all devices.

Using the Third Party Sensors

The sensor sold on ebay is "Normally Open". So you have to reverse the control and feedback Signals. Here is how:

  • In KPL Button dialog, make sure button A sends "Off" signal and button "C" sends on signal.
  • In "UI" panel, add both "Reverse Control" and "Reverse Feedback" properties to the IOLinc load device.

    For more information, please refer to UI Node Properties.