Virage Labs

Setup

Virage products work out-of-the-box with three major open-source Home Automation hub systems:

To set up your Virage devices on these, follow the instructions below.

Home Assistant

Virage WiFi-based products (e.g. plugs, lights, switches, bridges) interface with Home Assistant via the Mosquitto MQTT integration.

This integration requires that you set up the Mosquitto MQTT Broker Add-on in Home Assistant (from the Add-on Store, under the Supervisor menu), or that you have a compatible MQTT broker running on your LAN. Note that Virage devices by default assume that the MQTT broker requires authentication, and use ‘mqttuser’ and ‘mqttpass’ as the username and password.

Once you have a working MQTT Broker (we recommend using the built-in one in Home Assistant), you need to install the Mosquitto MQTT integration. To do this, go to the Configuration menu, and choose Integrations. If you’ve installed the built-in MQTT broker, it should be detected automatically and there should be an entry in the list of integrations to set up MQTT (you may have to restart Home Assistant). Otherwise, you can add it manually by clicking the blue + sign in the lower right of the window and choosing MQTT. When you install the MQTT Integration, be sure to enable Automatic Discovery, which will let Home Assistant find your Virage devices.

That’s it – you’re almost ready!

Before you start installing your Virage devices, to help you install and manage them, we have developed some additional software you can install (available on our GitHub site):

First, to allow your WiFi-based devices to easily find your Home Assistant installation, we have built an Add-on called Virage Avahi MQTT to advertise both the name of your Home Assistant installation, and the presence of an MQTT broker.

Second, so that your devices don’t ‘disappear’ into your LAN, we have built the Virage Dashboard, which is an integration for Home Assistant that creates a page to group all of your Virage devices in one place, let you easily access the built-in configuration page on each of your devices, and add/configure RF-based Virage devices (e.g. door contacts and motion sensors). The integration is available on our GitHub site, or through HACS, and once installed can be accessed through a menu item on the side bar.

If you are using a VirageHub, or an Argon One m.2 case for a Raspberry Pi, we have also created Add-ons to enable and configure the built-in fan in the case. If you are using a VirageHub, or a Raspberry Pi 4-based installation with minimum 32GB SSD, you can also use the Virage Home Assistant image which comes pre-configured with all of the software mentioned above and will let you hit the ground running with a fully functional Home Assistant installation.

To access the Virage Add-on repository click the button below, or add https://github.com/viragelabs/addons to the repositories list in your Add-on Store:

Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

It is recommended to install the Virage Avahi MQTT Add-on prior to setting up your devices to ensure that they are able to easily find your Home Assistant installation. The Virage Dashboard may be installed at any time, but again installing it before you start setting up your devices will make it easier to verify they have connected properly to Home Assistant and to find your devices on your LAN if you need to make any changes.

Once the above is done, you can begin setting up your devices following the instructions in their respective manuals. They should be automatically detected and installed by Home Assistant, and available for immediate use.

To install RF-based devices, such as door contacts or motion detectors, first ensure that you have at least one VirageBridge installed and set up in Home Assistant. This is needed to receive the RF signals and translate them into a format Home Assistant can understand. Next, install the Virage Dashboard (if you have not done so already), following the instructions in HACS or on the Virage Dashboard GitHub page, and making sure to set up automations based on the three Door Contact Blueprints.

Once the Virage Dashboard is properly installed, click on the Virage Dashboard menu item in the sidebar, and then toggle the Enable Discovery switch (under Add Door Contact or Motion Sensors) to ‘on‘. Trigger your door contact or motion detector, and you should see icons appear in the space below. Once something has been detected, the Enable Discovery switch will automatically turn itself off. You can simply turn it back on again for each device you want to set up.

You can rename the discovered RF-based devices as necessary by clicking on them and selecting the configuration (gear) icon in the top right corner of the dialog box. Once renamed, they will disappear from the newly discovered area, and reappear in the left-hand column, under the appropriate section.

Note that you can have as many VirageBridges on your LAN as are needed to provide optimal coverage for your home or building – they appear as separate devices within Home Assistant, but the RF signal processing is done in such a way that they all appear as one. This provides easy scalability as well as redundancy.

Domoticz

Virage products can be set up in Domoticz via MQTT in one of two ways, using automatic MQTT Discovery, or manually through the MQTT Client Gateway with LAN interface.  Either option requires a functioning MQTT Broker on your network. Note that installing RF-based Virage devices requires a VirageBridge, as well as the creation of some simple automations, which are described below.

Mosquitto (https://mosquitto.org/) is a lightweight MQTT broker available for a number of systems including Windows, Mac, Raspberry Pi and various versions of Linux.  A good tutorial on installing and configuring Mosquitto on a number of systems can be found here.  There are also a variety of cloud-based MQTT brokers, however these create additional security considerations.  If you do not understand these potential security issues, it is strongly advised that you use a locally-installed MQTT broker. If you are using a VirageHub, or a Raspberry Pi 4-based installation with minimum 32GB SSD, you can use the Virage Domoticz image which comes pre-configured with Mosquitto and Avahi to help Virage devices automatically find it.

Note that Virage devices by default assume that the MQTT broker requires authentication, and use ‘mqttuser’ and ‘mqttpass’ as the username and password.

You may change these if you wish to enhance the security of your connection, however assuming all of your Virage devices are installed in a secure local area network (LAN), protected by a firewall and strong WiFi password(s), this should not be necessary.

Once you have a functioning MQTT broker on your network, you may then proceed to install the MQTT connections on Domoticz and your Virage hardware.

 To install automatic MQTT Discovery:

  1. Download the plugin from https://github.com/viragelabs/domoticz_plugin and copy the plugin.py file into /domoticz/plugins/virage_mqtt_discovery/ on your Domoticz server (you will need to create the virage_mqtt_discovery directory).
  2. Restart your Domoticz server
  3. Go to the Setup menu, then Hardware, and create a new entry of the type Virage MQTT discovery.
    • Note that the plugin currently only works with systems using Python 3.8X or below. If you system does not meet these requirements, it may hang when rebooting. If this is the case, simply remove the plugin and your system should boot normally. It is possible to downgrade the version of Python on your system to make the plugin work.
  4. Enter a Name, the MQTT Server Address, Username, and Password for your MQTT Broker.  Leave the other fields at their default settings.
  5. Click Add, and you will be prompted to look in the Devices area (under Setup) for discovered devices.
  6. Once the above is done, you can begin setting up your devices following the instructions in their respective manuals.
    • The Virage MQTT Discovery function of Domoticz will automatically find and configure the VirageSwitch, VirageDimmer, and ViragePlug, and the controls for these devices, once discovered, can be found in the Switches tab.
    • The VirageBridge, and associated door contacts or motion sensors, requires manual configuration in Domoticz – please wait to set up you VirageBridge until you have read the section below.

To install the VirageBridge and door contacts or motion sensors:

  1. Do not configure your VirageBridge via the built in configuration page until you have completed the first 7 steps of this procedure
  2. Go to the Setup menu, then Hardware, and create a new entry of the type MQTT Client Gateway with LAN interface.
  3. Enter a Name, the MQTT Server Address, Username, and Password for your MQTT Broker.  Leave the other fields at their default settings.  You may use any name you wish for the Client field.
  4. Click Add.
  5. Create another entry in Hardware of the type Dummy (Does nothing, use for virtual switches only).
  6. In the Type column, in the row for this new entry, click the Create Virtual Sensors button
  7. In the dialog box that opens after clicking the button, name the new virtual sensor RF Data, and use Sensor Type Text.  This sensor will receive data from your VirageBridge and make it available for processing within Domoticz.
  8. Go to the Utility tab.  You should now see an entry for the RF Data sensor you created, with the text “Hello World”.  Click Edit and note the Idx number.
  9. You may now configure your VirageBridge using the instructions in the manual.  Enter the Idx number from step 8 in the space provided in the VirageBridge built-in configuration page.
  10. Trigger the first motion sensor or door contact you want to set up.  You should see the text in the RF Data sensor (on the Utility tab) change to a number.  Door contacts will have a different number for closed and open states, motion sensors will only have one (transmitted when they are triggered).  Record these numbers (keeping track of which motion sensor or door contact they belong to), and do the same for each of the other sensors you want to set up.
  11. Return to the Hardware screen and click the Create Virtual Sensors button associated with the Dummy created in Step 5.
  12. Name this new virtual sensor to reflect the first door contact or motion sensor you want to set up, and use Sensor Type Switch. Repeat this for as many motion sensors/door contacts as you wish to set up.
  13. Go to the Switches tab and scroll to the bottom, you should see the virtual sensors you just created listed.
  14. Click Edit on the first one, note the Idx (and the motion sensor/door contact it is associated with), and change the Switch Type to Door Contact or Motion Sensor as appropriate.  Note that motion sensors only produce an ‘on’ signal, which is retained until it is manually cleared, see the script example below for a method to clear the state of the sensor after some period of time.  Click Save.  Repeat this for each of the virtual sensors you created in Step 11.
  15. For each sensor you wish to set up, you should now have an associated 6 to 8 digit number, and an Idx
  16. Proceed to Setup, select More Options and then Events
  17. Click the + sign to start a new script, choose dzVents, and then Minimal
  18. Modify the script in the editor window to suit your hardware using the sample code below (note that — denotes comments):

return {

— VirageBridge 1 and 2 (idx 1 and 2)

    on = { devices = { 1,

        2 }

    },

    execute = function(dz, item)

— Door Contact (idx 3) and Motion Sensor (idx 4)

        local switch1 = dz.devices(3)

        local switch2 = dz.devices(4)

        if item.rawData[1] == “AAAAAA” then — ‘Open’ code

            switch1.switchOn()

        elseif item.rawData[1] == “BBBBBB” then — ‘Closed’ code

            switch1.switchOff()

        elseif item.rawData[1] == “CCCCCCC” then — ‘Motion’ code

            switch2.switchOn().forSec(5)

        end

    end

}

In the second line of the example above, 1 and 2 are the Idx‘s of the RF Data sensors (and the Idx’s entered into the VirageBridge setup screens).

local switch1, and local switch2 are the virtual sensors set up for a door contact and a motion sensor, respectively.  The numbers in brackets eg. dz.devices(3) and dz.devices(4) are the Idx’s of each virtual sensor.

AAAAAA is the number received on the RF Sensor indicating the door contact associated with Idx 3 is open, BBBBBB means this contact is closed.  CCCCCCC is the value indicating the motion sensor (Idx 4) has been triggered. The .forSec(5) command instructs Domoticz to keep the motion sensor state on for 5 seconds, then turn it off

Note that the statements for the door contacts are in pairs (to switchOn and switchOff the virtual sensor), while there is only a switchOn statement for the motion sensor.

You may add as many door contact or motion sensors as necessary by adding more local switches and elseif statements to the script.

Click Save to save the script when you are done editing it.  Your door contacts and/or motion sensors should now be set up and visible on the Switches tab.

OpenHab

Virage products communicate with OpenHAB via the OpenHAB MQTT binding (https://www.openhab.org/addons/bindings/mqtt/).  The MQTT binding in turn requires a functioning MQTT Broker on your network.

Mosquitto (https://mosquitto.org/) is a lightweight MQTT broker available for a number of systems including Windows, Mac, Raspberry Pi and various versions of Linux.  A good tutorial on installing and configuring Mosquitto on a number of systems can be found here.  There are also a variety of cloud-based MQTT brokers, however these create additional security considerations.  If you do not understand these potential security issues, it is strongly advised that you use a locally-installed MQTT broker. If you are using a VirageHub, or a Raspberry Pi 4-based installation with minimum 32GB SSD, you can use the Virage OpenHab image which comes pre-configured with Mosquitto and Avahi to help Virage devices automatically find it.

Note that Virage devices by default assume that the MQTT broker requires authentication, and use ‘mqttuser’ and ‘mqttpass’ as the username and password. You may change these if you wish to enhance the security of your connection, however assuming all of your Virage devices are installed in a secure local area network (LAN), protected by a firewall and strong WiFi password(s), this should not be necessary.

Once you have a functioning MQTT broker on your network, you must install the MQTT Binding on OpenHAB.

  1. To do this, navigate to the OpenHAB interface in your browser, select the Settings menu (visible only to Administrators), then choose Bindings, under the Add-Ons section.
  2. If you do not see MQTT Binding already listed, click the blue plus sign in the bottom right corner of the window, scroll down to MQTT Binding, click on it, and choose install.

You should now see MQTT Binding listed under installed Add-Ons.

  • Next, navigate back to the Settings menu and choose Transformations, under the Add-Ons section.  In order to enable certain Virage devices to be automatically discovered, the MQTT Binding requires the Jinja Transformation and the JSONPath Transformation to be installed.
  • If these are not already listed, click the blue plus sign in the bottom right of the window and install them.
  • You should now see an option on the Settings menu for MQTT System Broker Connection under the Other Services section.
  • Click on this and configure the Connection Name, Broker Host (the IP address or hostname of your MQTT Broker), Broker Username and Broker Password to match what was configured on your MQTT Broker (the other settings below can be left at defaults).

Virage products support secure MQTT connections over TLS, however this is disabled by default and it is recommended to leave the Secure Connection? option in OpenHAB disabled.

  • Navigate to the Things view, at the center bottom of the window, click the blue Inbox button (this may take a few minutes to appear).  You should now see MQTT Broker listed.  Click it, and choose Add as Thing.

You are now ready to begin installing your Virage devices.

Once you have completed the above steps, and your Virage devices are connected to your WiFi network and configured to connect to your MQTT Broker (as per the product manuals), they should be detected by OpenHAB.

  1. Open the OpenHAB interface in your browser, and navigate to Things.
  2. At the center bottom of the window, you should see a blue Inbox button.  Click this button, and OpenHAB will display all of the devices that have been discovered.
    • Note that at this time, OpenHAB is only capable of automatically configuring switches and plugs.  VirageDimmers and VirageBridges will need to be configured manually (see instructions below).
  3. For VirageSwitches and ViragePlugs, click the entry in the Inbox, and choose Add as Thing (with or without a custom ID).
  4. Your device will be set up as a Thing and automatically configured with channels for Status, and for each switch (one for a VirageSwitch, or three for a ViragePlug).
  5. Go back to the Things menu, and click on the entry for the device you just added.
  6. Go to the Channels tab (centre-top of the window) and click Add Points to Model.
  7. In the new window, choose which of the Channels you want to add to the Model
    • state is the channel used to control the switch (note there will be three state channels for a ViragePlug), status is a sensor that displays the strength of WiFi signal at the device.
  8. As you check the box(es) beside the Channels you want to use, be sure to edit the Label field to give the items you are creating a friendly name.
  9. Once you have completed your choices and given the channels appropriate names, click Add to Model.  The switch and/or status items you have created will now be available in both the Model and Items views and can be added to Pages in the front end as any other device.

If you are installing a VirageDimmer or VirageBridge, some manual configuration is necessary:

  1. First, from Inbox in the Things view, note the 6 character identifier beneath the name of each discovered device (this will be all capital letters and numbers).
    • Do not add the detected devices as things.
  2. Next, click the blue plus sign in the lower right corner of the window, choose MQTT Binding, and then click Generic MQTT Thing from the Add Manually section.
  3. Enter an appropriate name for your Thing in the Label field
  4. Under Bridge, associate the new Thing with the MQTT Broker.
  5. Check the Show Advanced box to reveal additional settings.
    • For a VirageDimmer or VirageBridge:
      • In the Availability Topic field, enter:
        • tele/VirageDimmer_XXXXXX/LWT
        • or
        • tele/VirageBridge_XXXXXX/LWT (where XXXXXX is the six-character identifier for the device you are installing)
  6. In the Device Available Payload field, enter
    • Online
  7. In the Device Unavailable Payload field, enter
    • Offline
  8. Click Create Thing.

Return to the Things view, and you should see the Thing you just created.  Click on it, and then click on Channels (centre top).  Click Add Channel.

For a VirageDimmer:

  1. Choose Channel Type Percentage Value (this is the Dimmer channel)
  2. In the MQTT State Topic field, enter
    • stat/VirageDimmer_XXXXXX/RESULT
  3. In the MQTT Command Topic field, enter
    • cmnd/VirageDimmer_XXXXXX/Dimmer
  4. In the Absolute Minimum field, enter
    • 0 [the numeral zero]
  5. In the Absolute Maximum field, enter
    • 100
  6. Check the Show Advanced box
  7. In the Incoming Value Transformations field, enter
    • JSONPATH:$.Dimmer
  8. Click Create
  9. Click Add Channel again
  10. Choose Channel Type On/Off Switch (this is the Light Switch channel)
  11. In the MQTT State Topic field, enter
    • stat/VirageDimmer_XXXXXX/RESULT
  12. In the MQTT Command Topic field, enter
    • cmnd/VirageDimmer_XXXXXX/POWER
  13. Check the Show Advanced box
  14. In the Incoming Value Transformations field, enter
    • JSONPATH:$.POWER
  15. Click Create
  16. You may now click Add Points to Model as described above for the VirageSwitch and ViragePlug.

For a VirageBridge:

  1. Choose Channel Type Text Value (this channel shows the sensor data received by the VirageBridge)
  2. In the MQTT State Topic field, enter
    • tele/VirageBridge/RESULT
  3. Check the Show Advanced box
  4. In the Incoming Value Transformations field, enter
    • JSONPATH:$.RfReceived.Data
  5. Click Create
  6. Your VirageBridge is now set up.  It is now necessary to create another Channel for each door contact or motion sensor you want to set up.
  7. From the Channels tab for your VirageBridge, click on the channel you just created.
  8. Trigger the motion sensor or door contact
  9. A text code should appear to the right of the Channel name – this is the unique ID of your motion sensor or door contact.
  10. Motion sensors have one code when they are triggered, door contacts have an open and closed state.  For door contacts, the codes will be XXXXXA (A indicates open), or XXXXXE (E indicates closed).  Write down the code(s) for the sensor you are setting up.
  11. Click Add Channel again
  12. Choose Channel Type Open/Close Contact (this will show the state of the sensor you are setting up)
  13. In the MQTT State Topic field, enter
    • tele/VirageBridge/RESULT
  14. In the Custom On/Open Value field, enter:
    • XXXXXA (for door contacts)
    • Or
    • XXXXXX (for a motion sensor)
  15. In the Custom Off/Closed Value field, enter:
    • XXXXXE (for door contacts)
    • Or
    • Leave blank for a motion sensor
  16. Check the Show Advanced box
  17. In the Incoming Value Transformations field, enter
    • JSONPATH:$.RfReceived.Data
  18. Click Create
  19. You may now click Add Points to Model for the Door Contact or Motion Sensor as described above for the VirageSwitch and ViragePlug.

Note that Virage motion sensors (and most others on the market) only transmit a signal when they detect motion, thus the state of the motion sensor will remain triggered (OPEN) indefinitely.  To remedy this condition, you can create an automation that triggers when the state of the sensor is updated, waits for a specified period of time, then changes the state of the sensor back to CLOSED.