LightwaveRF

evasmolders edited this page Dec 29, 2016 · 3 revisions
Clone this wiki locally

Introduction

LightwaveRF (hereafter LWRF) is a line of home automation from JSJS Designs. The main website can be found at http://www.lightwaverf.com/, with a very handy forum at http://lightwaverfcommunity.org.uk/forum/

The first release of LightwaveRF devices are "one way", in that you can issue them commands, but you cannot read their status.

People on a budget can buy a LWRF device and a compatible switch to turn it on, off or (if it's a light) dim it - but those of you wanting to automate things will need the "WiFi Link" : http://www.lightwaverf.com/store/home-automation-controls/smart-homes-wifi-link

The name is misleading, as the device is wired to your network, but does use wireless signals to control the LWRF devices. The controller needs 1 x CAT5 lead and socket on your router, and 1 x power connection.

LWRF devices range from simple "on/off" relays, to dimmable lights, door locks, heating (radiator) valves, boiler controls, energy monitors and more. For the whole range, see the website linked above.

If you have the right LWRF equipment (see below) then you can link OpenRemote with LWRF via the UDP control interface - although as mentioned, the first range of devices are one way, and cannot be queried.

Hardware

To integrate OpenRemote and LightWave, we have tested the products listed in the table below.

For a basic setup, you will need:

  1. OpenRemote Controller installed on your PC, RPi, NAS, etc.
  2. OpenRemote Designer Account
  3. A web browser, Android or iOS device for control
  4. A LightwaveRF WiFiLink
  5. A LightWaveRF device to control - see http://www.lightwaverf.com/store

Beyond that, you can add any "LightwaveRF" certified device.

Configuration of System

Pre-requisites:

Once you can control LWRF via the LWRF website, you should be able to control it via OpenRemote.

Installation

LWRF works on the principle of Rooms and Devices. This is primarily so you can group devices to make them easier to find on the application & website, control an entire room at once (power everything down) etc.

Rooms

Using the LWRF website (or app, if you've installed it) you can create rooms (up to 8). Within the application or website you can define a name for each Room, although for OpenRemote the name is not used.

These rooms can later be referenced by the letter R and the room number, with the first room being 1, so R1 for Room 1, R2 for Room 2 etc.

Devices

Similar to Rooms, each Device within a Room is addressed with the letter D and the relevant number. D2 for Device 2 for example.

Again, you can name each device in the application or website, but OpenRemote does not use the name.

Network Control

Once your LWRF WiFi Link is setup and synced with your LWRF account, it will have access to control each Room and Device you have defined. You can also access the WiFi Link and issue commands to it, via UDP - which is where OpenRemote comes in!

However, a recent change in LightwaveRF firmware means you must first 'pair' your controller with your WiFiLink. To do this, you need to issue:

001,!F*p

This should cause your WiFiLink screen to display a message confirming you wish to pair, with a Yes or No option. Press the "Yes" button to enable your device to link.

Use the above command with the example OR structure below, and create a REGISTER command, and link it to a button for later use. Once you've registered, you can remove the button.

Communications

Protocol & Port

The WiFi Link uses UDP port 9760 to listen for/receive commands. It also issues responses back, but does so to the issuing device (i.e. OpenRemote) on port 9761.

Format

The WiFi Link expects commands in a defined format, which is shown below :

001,!R2D1F1|Ceiling Lights|On

So, let's break that down...

001 This is an instruction number. It should start at 001 and can increase. It can be used when sending multiple instructions to the WiFi Link - but with OpenRemote, typically only one command is sent at one time.

,! The comma (,)and exclamation mark (!) are required. The ! instructs LWRF to send the command.

R2D1F1 As mentioned above in Rooms and Devices, this is where you put the Room and Device address of the LWRF node you want to control with this instruction. In this example it's Room 2, Device 1.

The F part which follows R2D1 is for Function. F1 means On F0 means Off

So, in this example, we're turning Room 2, Device 1, On.

| The pipe (|) symbol is required.

Ceiling Lights This is free message text. The V1 WiFi Link has a two line LCD display. This piece of text will be displayed on the first (top) line.

| This second pipe (|) symbol is required.

On This is free message text. This piece of text will be displayed on the second (bottom) line of the WiFi Link LCD.{info}

So, when you finally issue this command, the WiFiLink will (or should!) display :

Ceiling Lights On

OpenRemote Designer Configuration (putting it all together)

Create a device within OpenRemote, and then Create a command, as follows :

KAKU-COCO - table1

Save that, assign the command to a button and give it a go!

You'll need two versions of each command, one for On and one for Off, with the only difference being the F1 and F0 parts of the string, and the last piece of free message text.

h3. Device State Tracking

Previously, it was noted that V1 LWRF devices are "one way" - so whilst you can control them, you can't query what state they are (other than by using a Mk 1 Eyeball). However, in the author's experience:

  • LWRF always issues commands as specified
  • LWRF devices always receive them and act on them
  • Unless you use the native application or website, you won't be out of sync
  • Even if you do use the native application or website, you'll only have to press an OR button twice to get back in sync

OpenRemote lets you create switches to toggle things on and off, or you can use image buttons with different states. The author uses a lit and unlit lightbulb for some of his lights for example.

To do this is perfectly possible, but requires a little bit more effort.

Firstly, create both your On and Off commands for your device, as per the example above. For ease of reference in this example, let's say we created our commands and named them as follows

  • Ceiling_Light_On
  • Ceiling_Light_Off

Virtual Commands

Secondly, you'll need to create three _In-memory Virtual Command_s (IMVC). Ultimately this is a way of creating and controlling a variable (i.e. something you can assign a state to) within OpenRemote.

To do this, create a new Command as follows :

KAKU-COCO - table2

You will then need to create a further two IMVCs. They should be almost the same as the IMVC you just created, except this time set the Names and Commands as follows :

KAKU-COCO - table3+4

Ensure you keep the Address the same in all three IMVCs. If you don't, it won't work. It's also recommended you relate the IMVC address to the device you're using for ease of reference - hence R2D1togglestate in this example.

These IMVCs are now able to control an OpenRemote variable called R2D1togglestate - although on their own, they don't do anything.

Then you need to create a Sensor - so within your OpenRemote device, create a new Sensor as follows :

KAKU-COCO - table5

This gives you a Sensor, which uses the command Ceiling_Light_Get_State you created previously. This basically tells OpenRemote to monitor the IMVC you linked to that command (i.e. R2D1togglestate).

Now finally, you can create an OpenRemote switch. Within your OpenRemote device, create a new Switch as follows:

KAKU-COCO- table6

So let's recap - by now you should have :

  • Five commands
    • Two to actually issue LWRF commands to turn the LWRF device on and off
    • Three IMVCs (which are controlling a variable for the LWRF device state)
  • One sensor (to monitor the variable)
  • One switch (to use on the OpenRemote interface)

OpenRemote Rules (getting it working)

So far, nothing is actually triggering the IMVC variables, so we need to change that....

So now you'll you need to define a little bit of code within OpenRemote. This is by no means as scary as it sounds. Within the OpenRemote designer, select the Building Modeller screen, then select Config for Controller and then click on Rules.

In the rules.editor window, you need to add the following text :

rule "Turn_Ceiling_Lights_On"
when
    Switch( source == "Sensor_Ceiling_Light_State", value == "on" )
then
  execute.command("Ceiling_Lights_On");
end

rule "Turn_Fireplace_Lights_Off"
when
    Switch( source == "Sensor_Ceiling_Lights_State", value == "off" )
then
  execute.command("Ceiling_Lights_Off");
end

The above code creates two rules. If you follow the fairly simple code, you can see that the rules are monitoring for Switch events, coming from the source, which in this case is Sensor_Ceiling_Light_State. When the value changes to on or off they call the actual LWRF command to turn the LWRF device on or off as necessary.

So - the Switch calls the IMVC commands (Set_On and _Set_Off), which updates the value stored within R2D1togglestate. The Sensor is activated by the variable changing, and this in turn triggers the event defined in the Rules, which in turn actually run the command to turn the device on, of off.

Whilst this seems very long winded, it's the only way for OpenRemote to track if a device has been turned on, or off.

You can now create a Switch on the OpenRemote UI Designer panel and assign it your defined Switch command (Ceiling_Light_Switch) and assign graphics for the on and off states as appropriate.

As mentioned, if you also (or remotely) use the native LWRF applications to turn a device on or off, then OpenRemote will be out of sync with the device state. But don't worry, if you use OpenRemote to issue an "on" command to a device that's already on, (or off to one that's off) - nothing happens - but OpenRemote will still issue the command and update it's UI - so the worst case is you have to press a button once to get back into sync :)

If you want to get the full command list, you'll have to apply for the official API, which is not re-distributable. The above info has been gleaned via use of WireShark and Google. You can apply for the API here.

See also