Home
Lightwave Link: Heating

Heating

Heating Introduction

Heating products were the first products in the LightwaveRF line up which had the ability to both send and receive radio packets. The Link will receive data from these devices and is able to interrogate them for their status. This allows the Heating products to be the first products which LightwaveRF offer which are able to be controlled, then check that the control was received by the peripheral device.

The heating products consist of:

Boiler Switch (LW920)
Home Thermostat (LW921)
Thermostatic Radiator Valve (AKA the TRV) (LW922)
Electric Switch (LW934)

The Home Thermostat is able to link to each of the other three products. It is required to link to the Boiler Switch to control the Boiler Switch, as the Boiler Switch is reliant on external control from the Home Thermostat. The Boiler Switch won’t be discussed in the remainder of the Heating section in reference to control from the Link as it is unsupported.

Note
Heating devices require the Link to be running on a version which is prefixed with U or N. Links which are prefixed with V do not support heating, though they can have their firmware changed to U by contacting support.

General Heating Operation

All heating products behave similarly in their standard operation, and it is unique within the LightwaveRF range. The devices have the ability to store the current time, and they store the times that they should switch internally as opposed to lighting and power products which switch based on the settings the Link unit has. This allows each peripheral to act independent of the Links presence, if the peripheral has the received the time.

The time is sent out to each peripheral when it boots up, and if a paired Link unit is present. If the Link detects that the peripheral does not have the correct time, it will respond to the peripheral with the time.

Switching

The devices will target a specified temperature and switch on and off (or on a TRV open and close) based on the temperature that they read, in comparison to the temperature they are set to. If the target temperature is 0.5C above the current temperature, the device will then switch off. If the target temperature is 0.5C below the current temperature, the device will then switch on.

Scheduling

Each device is capable of storing a schedule for each day of the week, with each day broken up into 96 fifteen minute segments. The devices will then be able to target a single “setback” temperature as well as up to five “on” temperatures throughout each day.

The setback temperature is used when the device is not in an “on” period to have a target temperature the device never falls below. For example, it is very rare for heating device to be required to be switched off completely as this can allow frost/damp to occur, whereas targeting a low temperature such as 10C allows a property/room to warm enough enough so that this is not a problem, but still not to have the heating on unless in extreme circumstances.

If the user sets a temperature out of the schedule, the device will then follow this new target until the next change in schedule. Once the schedule changes, the device will revert to its original schedule and will not then change the target for the schedule on any other days.


Linking

Linking a heating/energy device is done differently from the linking of a lighting power device. The heating/energy devices have linking information stored in themselves, as well as the Link storing information about the devices product type and serial.

The Link is able to connect to up to 80 heating devices, though it shares the same space with energy devices, so if there any energy devices linked, this number will be 80 minus<number of energy devices>.

To link a device, the Link must first enter linking mode. To send the Link into linking mode, the client should choose the appropriate slot number they want to assign to the device (1 to 80) and send the below command:

!R_F*L

where _ is the slot number chosen.

Note
Despite the command beginning with R, this is not related to lighting/power/moods or any room control. Linking a device to R1, then sending !R1Fa (Room 1 All Off) would not turn the heating device in slot 1 off.

Once the command has been sent and the Link has given the OK response, then the user would be able to place their peripheral into linking mode for it to connect to the Link. A successful link will have the Link output:

*!{
    "trans":123,
    "mac":"XX:XX:XX",
    "time":1420070400,
    "pkt":"868R",
    "prod":"tmr1ch",
    "serial":"ABC123",
    "type":"link",
    "room":1,
    "pairType":"product",
    "class":"",
    "msg":"success"
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt 868R This communication is a result of 868MHz radio being received)
prod tmr1ch The type of product that has been added is a Thermostat (tmr1ch = Timer 1 Channel)
trv The type of product that has been added is a TRV
electr The type of product that has been added is a Electric Switch
serial ABC123 The serial number of the product which has been added
type link The type of packet the Lightwave Link is sending is a “link” packet
room 0-80 The slot number which the device has been added to
pairType product This link packet is referencing the addition of a new product (as opposed to a local phone/tablet/PC)
class n/a unused
msg success The linking has been successful

Unlinking

To remove a previously added heating/energy device, the process is similar to linking.

To unlink a device, the client should choose the appropriate slot number they want to remove from the Link (1 to 80) and send the below command:

!R_F*xU

where _ is the slot number chosen.

The peripheral does not need to be placed into linking mode for this as the Link unit will remove the pairing in itself and will no longer output any data the peripheral broadcasts out.

A successful unlink will have the Link output:

*!{
    "trans":123,
    "mac":"XX:XX:XX",
    "time":1420070400,
    "pkt":"868R",
    "type":"unlink",
    "room":1,
    "pairType":"product",
    "class":"",
    "msg":"success"
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt 868R This communication is a result of 868MHz radio being received (in this instance, this is incorrect)
type unlink The type of packet the Lightwave Link is sending is an “unlink” packet
room 0-80 The slot number which the device has been added to
pairType product This unlink packet is referencing a product which is being removed
class n/a unused
msg success The unlinking has been successful

Reading Heating Devices

Additionally, it is also possible to obtain the current record for the devices stored in the Link to understand how many are currently stored, and what the IDs of them are, and what type of device is stored in each slot. This is only for heating and energy devices.

The devices are stored in an internal table of 80 rows, and you can interrogate which rows in the table have been used by sending the command @R. The Link will then respond with:

*!{
    "trans":36409,
    "mac":"XX:XX:XX",
    "time":1420070400,
    "pkt":"room",
    "fn":"summary",
    "stat0":7,
    "stat1":0,
    "stat2":0,
    "stat3":0,
    "stat4":0,
    "stat5":0,
    "stat6":0,
    "stat7":0,
    "stat8":0,
    "stat9":0
}

where the first three values are the same, and the following are:

Name Value(s) Description
pkt room
fn summary This packet is a summary of the Room details
stat0 255 Convert this to binary to find out which slots are in use for slots 1-8
stat1 255 Convert this to binary to find out which slots are in use for slots 9-16
stat2 255 Convert this to binary to find out which slots are in use for slots 17-24
stat3 255 Convert this to binary to find out which slots are in use for slots 25-32
stat4 255 Convert this to binary to find out which slots are in use for slots 33-40
stat5 255 Convert this to binary to find out which slots are in use for slots 41-48
stat6 255 Convert this to binary to find out which slots are in use for slots 49-56
stat7 255 Convert this to binary to find out which slots are in use for slots 57-64
stat8 255 Convert this to binary to find out which slots are in use for slots 65-72
stat9 255 Convert this to binary to find out which slots are in use for slots 73-80

To identify which slots are used, you will need to turn the value in statX to a binary format, with the least significant bit (LSB) being the value at the right.

Examples:
stat0 - 00000001 would indicate that the only device slot in use between 1-8 would be in slot 1.
stat0 - 00000011 would indicate that the device slots in use between 1-8 are in slots 1 & 2.
stat0 - 00000100 would indicate that the only device slot in use between 1-8 would be in slot 3.
stat1 - 00000001 would indicate that the only device slot in use between 9-16 would be in slot 9.
stat2 - 00000011 would indicate that the device slots in use between 17-24 are in slots 17 & 18.
stat3 - 10000001 would indicate that the device slots in use between 25-32 are in slots 25 & 32.

For example, if the value is 21, then this converts to binary of 00010101, In the case of this, the slots in use are 1, 3 and 5.

With this information, it is then possible to check the information of the device in each slot by sending @?R_ where _ is the number of slot you’d like to check. @?R1, @?R2, @?R3@?R80, for example. The Link will then respond with:

*!{
    "trans":160,
    "mac":"XX:XX:XX",
    "time":1420070400,
    "pkt":"room",
    "fn":"read",
    "slot":"1",
    "serial":"123ABC",
    "prod":"valve"
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt room This JSON packet output relates to heating & energy devices
fn read The device is being read
slot 1-80 The slot the device is stored in
serial ABC123 The serial number of the device that is in this slot
prod valve, electr, tmr1ch, pwrMtr The type of product that is in this slot

If you check a slot which has no device stored in it using @?R_, then the Link will then respond with:

123,ERR,5,"Slot is empty"

for example:

Created with Raphaël 2.1.2ClientClientLinkLink123,@?R10123,ERR,5,"Slot is empty"

Communication to the Heating Products

In recent versions of the Lightwave Link and WiFiLink (2.92 onwards) there have been the introduction of JSON packets in response to almost all commands. When the Link receives the commands above, it will send an OK response initially (described in Example Interactions) suffixed with an "RFid" which denotes the ID of the radio it will send out, and then further packets detailing the communication. This will allow a client to decide whether the communication was successful or not, and take the appropriate steps as necessary (for example, to resend the radio, or to display an error to the user).

The heating products can accept many different commands to change targets, store schedules, change their mode and more. The packet contents will vary accordingly, but below is an example guide of the general communication based on a “Set Temperature” command:

S[255.255.255.255:9760]: 123,!R7FtP*17
R[192.168.1.103:9760]: *!{"trans":691,"mac":"03:34:BC","time":1475323582,"pkt":"868T","fn":"setTarget","room":7,"temp":17.0,"minutes":0,"packet":191}
R[192.168.1.103:9760]: 123,OK,{"RFid": 191}
R[192.168.1.103:9760]: *!{"trans":692,"mac":"20:04:96","time":1475323584,"pkt":"868R","fn":"ack","status":"success","attempts":1,"packet":191}
R[192.168.1.103:9760]:
*!{"trans,mac,time,pkt,fn,prod,serial,type,batt,ver...",state":"run","cTemp":22.0,"cTarg":17.0,"output,nTarg,nSlot,prof..."}

Created with Raphaël 2.1.2ClientClientLinkLinkPeripheralPeripheral123,!R7FtP*17(RF Target Temperature 17C)*!{"trans":691,"mac":"03:34:BC","time":1475323582,"pkt":"868T","fn":"setTarget","room":7,"temp":17.0,"minutes":0,"packet":191}123,OK,{"RFid": 191}(RF Message Acknowledged)*!{"trans":692,"mac":"20:04:96","time":1475323584,"pkt":"868R","fn":"ack","status":"success","attempts":1,"packet":191}(RF Update Status)*!{"trans,mac,time,pkt,fn,prod,serial,type,batt,ver...",state":"run","cTemp":22.0,"cTarg":17.0,"output/nTarg/nSlot/prof"}

Once the message has been sent, then the Link will go through numerous communications on UDP and RF.

The first response a client will typically receive if the command is successful is the Link broadcasting that it has just sent radio out. The JSON will detail the contents of the radio message broadcast.

The second message will be the standard OK response to your UDP command. This will come second as the Link needs to transmit the radio to obtain the Radio ID of the packet it transmitted. This ID is then suffixed to the OK message to allow a client to trace the command they sent, in the event that other RF comms are output subsequently.

If the RF was received by the peripheral, it will respond with an acknowledgement which the Link will output as a 868 receive message containing the ID of the acknowledged packet, and the number of attempts it had to output RF for the acknowledgement to be received. The link will automatically re-attempt an RF communication up to five times if no response is received.

Finally, the peripheral will action the received command and output its changes as a normal update. The Link will output this as an 868 receive message detailing the update that the peripheral has provided.

The acknowledgement can be used as confirmation of a successful end-to-end communication between a client, the Link and a peripheral, but the final update from the peripheral can be used as a double check that your intended command was acted upon.

Details of the packets received from a heating device are outline further below in Communication from Heating Products

Communication Errors with Heating Products

It is possible that communication is not able to be established with a peripheral. If the Link is not able to send the RF message out, it will output that there has been a “Transmit fail” instead of an OK:

Created with Raphaël 2.1.2ClientClientLinkLink170,!R5FtP*20170,ERR,6,"Transmit fail"

The transmit fail received could be a result of the Link processing another RF packet, or an invalid R slot having been sent by the client.

It is possible that the failure is down to the peripheral not responding:

Created with Raphaël 2.1.2ClientClientLinkLinkPeripheralPeripheral123,!R8F*r(RF Request Status)*!{"trans":718,"mac":"20:04:96","time":1475325023,"pkt":"868T","fn":"getStatus","room":8,"packet":202}123,OK,{"RFid": 202}*!{"trans":719,"mac":"20:04:96","time":1475325032,"pkt":"868R","fn":"ack","status":"fail","packet":202}

This example is similar to the successful example given earlier, as there is confirmation of the RF getting sent out, and the OK response going to the client. However, after approx 8-10 seconds of retrying, the Link did not receive any acknowledgement from the peripheral and posted out that the acknowledgement failed for that Radio ID.

The failure could be a result of the peripheral having no power, being out of range, or the peripheral itself having its memory cleared/getting linked to another controller. If the latter occurred, there is no communication to the Link to alert it that this has happened. It is also possible, but unlikely, that the peripheral is receiving the radio, but the acknowledgement response is not picked up by the Link.

In this situation, it should be taken that the peripheral device needs to be moved closer to the Link, or the batteries need to be checked.

Communication from Heating Products

The heating peripherals have the functionality to send out radio without being interrogated. The radio is usually only sent out when there is something new from the peripheral to output to the Link. The triggers for this will be the current temperature changing, the current target temperature changing or the current output changing.

*!{
    "trans":1080,
    "mac":"03:3F:D9",
    "time":1478694048,
    "pkt":"868R",
    "fn":"statusPush",
    "prod":"tmr1ch",
    "serial":"D41602",
    "type":"temp",
    "batt":2.47,
    "ver":34,
    "state":"run",
    "cTemp":25.0,
    "cTarg":18.0,
    "output":0,
    "nTarg":24.0,
    "nSlot":"06:00",
    "prof":1
}

where:

Name Value(s) Description
trans 1-4294967295 Transaction number of the JSON packet. Increments every transaction
mac XX:XX:XX Last 6 octets of Links MAC Address
time 1420070400 Timestamp of the transaction in a local UNIX time (i.e if Link is set to UTC+2, this time will be UNIX + (3600*2)
pkt 868R This communication is a result of 868MHz radio being received
prod tmr1ch The type of product that is communicating is a Thermostat (tmr1ch = Timer 1 Channel)
valve The type of product that is communicating is a TRV
electr The type of product that is communicating is a Electric Switch
serial ABC123 The serial number of the product which has been added
type temp The type of packet the Lightwave Link is sending is a “temperature” packet
batt 0.00-4.00 The battery level of the device. This is measured in volts. The battery powered products use 2x 1.5V AA batteries and will report in 3V or greater for a full battery. If the reading is less than 2.40V, this can be considered a low battery.
ver 0-999 The version of firmware running on the device
state run, man, frost, comf, away, boost, calib, hday, stby The current state/mode of the product. Further details of this are provided in the Mode section of the documentation
cTemp 0.0-40.0 The current temperature of the product in Celsius
cTarg 0.0-60.0 The current target temperature of the product in Celsius
output 0-100 The current status of the product. For a valve, this represents the % open that the TRV is. For a Thermostat, 0 means that it has sent off to its child device, and 100 means that is has sent on to its child device. For an Electric Switch, 0 means that the product is off, while 1 means that the product is on.
nTarg 0.0-40.0 The next temperature that the product will target, at the time specified in nSlot
nSlot HH:MM The next time that a change is set to occur in the products schedule
prof 0-15 The profile/mode that is currently running in the product. 1-7 represent Monday-Sunday. Other numbers are detailed in the Mode section of the documentation

Setting Temperatures

The heating devices can all be set to target a specific temperature which will change their behaviour to attempt to reach the specified temperature by switching the device on or off.

To set a temperature, the client should send:

!R_F*tPXX.X

where _ is the slot of the device they want to control, and X is the temperature that is desired. The temperature must be between 0C and 40C and must be sent in 0.5C increments.

If setting a temperature which is a round number, it is possible to send both !R_F*tPXX.0 or !R_F*tPXX to achieve the same result.

Target temperatures between 0C and 9.5C should be sent as a single whole number without a 0 prefix, such as !R_F*tP5.5 as opposed to !R_F*tP05.5.

TRV and Electric Switch Settings

The TRV and Electric Switch are also capable of going to non-temperature settings where the device will stay in a certain position regardless of the temperature. The setting is done in the same way a temperature is set, however a “fake” temperature is used.

An Electric switch can be set to stay off by sending a target of 50, and set to stay on by sending a target of 60.

A TRV can be set to open the pin in 10% increments, with 100% being fully open, and 0% being fully closed. The target temperatures are as follows:

Target Description
50 0% Open (i.e. fully closed)
51 10% Open
52 20% Open
53 30% Open
54 40% Open
55 50% Open
56 60% Open
57 70% Open
58 80% Open
59 90% Open
60 100% Open (i.e. fully open)

Note
The first party app uses TRV positions as 0, 1, 2, 3, 4 and 5 for similarity between a manual TRV so that the user has familiarity with the options. The app uses 20% increments, where position 1 is 52, position 2 is 54 and so on.

Manual Changes

Thermostat

When pressing the standby/power button on the Thermostat, the target temperature will alternate between the standby temperature, and the next/current “on” block.

i.e If the schedule is 15C setback, with 20C between 7AM-9AM and 22C between 5PM-10PM, and you press the standby/power button at 8AM, it will toggle between 20C and 15C. If you press the button at 1PM, it will toggle between 22C and 15C. This change will remain until the next scheduled change.

TRV

When pressing the standby/power button on the TRV, the output will alternate between fully on or fully off for one hour only. However, the target temperature does not change. This can cause an issue for the app/client as it is not immediately apparent that the user has manually intervened. It can be inferred by checking if the output is 0 or 100 when it should be.

Electric Switch

When pressing the standby/power button on the Electric Switch, the target will change to 50C or 60C (i.e. off or on) until the next scheduled change time. This will be reflected in any RF packets also.

Boost

Boost is used to increase the target temperature of a peripheral for an hour by 1.5C. There is some intelligence in the products when increasing the temperature. If the target is currently 20C and the current temperature is 17C, then the boost will not change the target, as the target has not actually been achieved. If the temperature was 22C, however, then the target would adjust to be 23.5C.

Setting Schedules

The heating devices can all be set to have a schedule which they will follow for each day of the week. Each schedule should contain at least one “on” block, with a limit of five “on” blocks per day.

To set a schedule, the client should send:

!R<SlotNo>F*s=N<Day>,Y<StandbyTemp>,T<TargetTemp>,S<StartTime>,E<EndTime>,T<TargetTemp>,S<StartTime>,E<EndTime>

Where:

   
SlotNo The Slot Number of the device to be controlled. Valid 1 to 80
Day Day of the week the schedule is referring to, with Monday being 1, and Sunday being 7. A can also be used for All Days, if a schedule for all seven days is desired
StandbyTemp The temperature to target when not in a heating period
TargetTemp The temperature to target for the hours specified in the next two fields
StartTime The time in HH:MM format for the previously specified target temperature to begin from. MM has to be 00, 15, 30 or 45
EndTime The time in HH:MM format for the previously specified target temperature to end at. MM has to be 00, 15, 30 or 45
TargetTemp, StartTime and Endtime can be repeated up to five times in each schedule

for example:

!R7F*s=N2,Y15,T22.5,S09:15,E11:30,T54,S14:00,E17:30

would store a schedule for the device in slot 7 to occur on Tuesday where the setback temperature is 15C, and the target will be 22.5C between 09:15 and 11:30, then have a TRV target position 40% between 14:00 and 17:30.

The heating products firmware is written in a way that has the start of the day at 06:00, and the end of a day at 05:59. The result of this is that when saving a schedule for Thursday, any heating which is due to switch between 00:00 and 05:59 needs to be added to Wednesdays schedule. The firmware of the heating products is not possible to be updated to alter this behaviour.

For example, if on a Thursday, you would like to have the heating set to 15C setback temperature, and 22C between 04:00 and 09:00, and again at 17:00 to 22:00, then you would need to have a schedule for Wednesday, to ensure the 04:00-06:00 part of Thursdays morning is covered:

!R7F*s=N3,Y15,T22,S04:00,E06:00

as well as any other blocks desired on Wednesday. The Thursday command would then be:

!R7F*s=N4,Y15,T22,S06:00,E09:00,T22,S17:00,E22:00

Note On earlier firmware of TRVs and Thermostats, there is an issue where an end time of 06:00 is not recognised. The client should use 05:45 as the last possible end time. This does result in the setback temperature running between 05:45 and 06:00, however. It is possible for a firmware upgrade to be applied to the units if ending the block at 05:45 is not suitable. This affect TRVs with a version less lower than 58, and Thermostats with a version less than 34.

Modes

The heating products support the concept of different modes they can be set to. These are then shown in any comms from the products as a “state”. The states are:

run, man, frost, comf, away, boost, calib, hday, stby

State Description
run Running Mode
man Manual Mode
frost Frost Mode
comf Constant (Comfort) Mode
away Away Mode
boost Boost Mode
calib Calibrate Mode
hday Holiday Mode
stby Standby Mode

Running Mode

run is generally one of the two standard modes you will find the devices in. run means that the heating device is doing its normal schedule and is in an “on” block.

Manual Mode

man is achieved on the TRVs when a customer has pressed the boost button on the TRV and the boost has expired. The TRV does not return back to run unless a battery pull has occurred. It is suggested that man and run be treated identically.

Frost Mode

frost is a mode on the Thermostat devices which can be achieved by the user setting this via the Mode button on the device, or from a Lightwave Link command. It will make the Thermostat target the Frost temperature stored in the device (accessible via the physical Thermostat menu) indefinitely in firmware versions of 58 or above, or for the remainder of the current day and the entirety of the following day in firmware versions below 58.

Constant Mode

comf is a mode on the Thermostat devices which can be achieved by the user setting this via the Mode button on the device, or from a Lightwave Link command. It will make the Thermostat target the Constant temperature stored in the device (accessible via the physical Thermostat menu) in firmware versions of 58 or above, or for the remainder of the current day and the entirety of the following day in firmware versions below 58.

Away Mode

away is a mode on the Thermostat devices which can be achieved by the user setting this via the Mode button on the device, pressing and holding the standby/power button or from a Lightwave Link command. It will make the Thermostat target the standby temperature stored in the device from its current schedule indefinitely in firmware versions of 58 or above, or for the remainder of the current day and the entirety of the following day in firmware versions below 58.

Boost Mode

boost is a mode on the Thermostat, TRV and Electric Switch devices which can be achieved by the user setting this via the Boost button on the device. It will make the Thermostat target a temperature 1.5C higher than the current target for one hour.

There is some intelligence in the products when increasing the temperature. If the target is currently 20C and the current temperature is 17C, then the boost will not change the target, as the target has not actually been achieved. If the temperature was 22C, however, then the target would adjust to be 23.5C.

Calibrate Mode

calib is a mode on the TRV which occurs when it is calibrating the length the pin can travel. It will occur when the TRV is first powered up, or when the TRV hits 0% when it does not expect to (i.e. too soon or too late). It is only a temporary state, and will return to run or man when the calibration is complete.

Holiday Mode

hday is a mode possible on the Thermostat where the device is put to a state where a single target temperature is maintained for a preset number of days. The temperature is able to be set on the physical device by utilising the menu options and choosing the desired holiday temperature here.

Standby Mode

stby is a mode on the Thermostat and Electric Switch products which occurs when they are running a normal schedule, but are not in a heating block. When the next heating block begins, the state will change to run.

It is possible to trigger a Thermostat to enter a mode by sending a command to the Lightwave Link. The command format for setting a Mode is:

!R_F*mPX

where _ is the slot of the device they want to control, and X is the mode that is desired. The mode must be between 0 and 5. The modes are:

Number Mode
0 Standby Mode
1 Running Mode
2 Away Mode
3 Frost Mode
4 Constant Mode
5,Y Holiday Mode. Y is used to define the number of days the Thermostat should enter Holiday mode for. !R_F*mP5,7 would result in Holiday mode getting set for 7 days.

Call For Heat

Introduction

Call for Heat is a feature introduced to the Lightwave Link in version 2.93 which allows the Link to turn a pre-set heating device on or off depending on the status of any other devices. This is a concept which works with heating so that a single device can give heat to other device(s) which are dependant on the single device to warm up.

A standard example is a domestic house which has a combi boiler that provides heat to each radiator. Any TRVs on these radiators can open and close depending on their own temperature and target, but they may not have any hot water to circulate. The central heating can be controlled by a Boiler Switch & Home Thermostat which are operating on a different heating schedule. With Call for Heat, if the Link detects any of these TRVs are open and will send a command to the Home Thermostat for it to switch on until further notice. Inversely, if all the TRVs are at or above temperature and are not open, the Link will send a command to switch the Home Thermostat off until further notice.

The device which switches on/off based on the status of the other devices is called the “Parent”, while the devices which determine if the parent should be on or off are called the “Children”. The Link supports 10 parents in its memory, with each parent able to have up to 8 children each.

It is possible for a child to also be a parent for more elaborate setups. Care must be taken to ensure a loop is not introduced where a devices child, grandchild, great grandchild etc is not a setup as a parent, grandparent etc.

Setup

Call for Heat must be setup with pre-existing devices so it is necessary to link all the products before going through the Call for Heat setup process. To begin the process of adding Call for Heat devices, the command structure is:

!RxPyF*C

Where x is the child device, and y is the parent. The Link will give its standard “OK” message back if this is setup correctly. If a the given x or y values are unknown, then this will return an “Unknown” error.

A successful process would be:

Created with Raphaël 2.1.2ClientClientLinkLink123,!R1P3F*C123,OK

While a unsuccessful process would be:

Created with Raphaël 2.1.2ClientClientLinkLink123,!R2P3F*C123,123,ERR,0,"Unknown"

To set up the device in slot 3 to be the parent of the devices in slots 1, 4, 5 and 8, you would send 4 commands:

!R1P3F*C
!R4P3F*C
!R5P3F*C
!R8P3F*C

It is not possible to remove Call for Heat children individually. However, it is possible to remove the parent, and therefore its children by sending !R_F*D where _ is the slot number of the parent device. From there, you can then re-add the children as appropriate by adding only the children that are desired.

To alter the example from above so that device in slot 3 is the parent of the devices in slots 1 and 8, but removing the devices in slots 4 and 5, the commands sent should be:

!P3F*d    //Removes the parent and child devices of slot 3
!R1P3F*C  //Re-adds slot 1 as a child of slot 3
!R8P3F*C  //Re-adds slot 8 as a child of slot 3

Reading the Call For Heat Setup

It is possible to check the current parents by sending out the @C command. This will return:

*!{
    "trans":152,
    "mac":"XX:XX:XX",
    "time":1479900687,
    "pkt":"parent",
    "fn":"summary",
    "stat0":1,
    "state":"on"
}

where the first three values are the same as other packets, and the following are:

Name Value(s) Description
pkt parent This packet details the parent devices
fn summary This packet is a summary of the parent device details
stat0 255 Convert this to binary to find out which slots of the 8 slots are in use
state on, off If Call for Heat is currently on or off

To identify which slots are used, you will need to turn the value in stat0 to a binary format, with the least significant bit (LSB) being the value at the right.

Examples:
stat0 - 00000001 would indicate that the only device slot in use between 1-8 would be in slot 1.
stat0 - 00000011 would indicate that the device slots in use between 1-8 are in slots 1 & 2.
stat0 - 00000100 would indicate that the only device slot in use between 1-8 would be in slot 3.

With this information, it is then possible to check the information of the parent in each slot by sending @?C_ where _ is the number of slot you’d like to check. @?C1, @?C2, @?C3@?C8, for example. The Link will then respond with:

*!{
    "trans":153,
    "mac":"03:3D:6B",
    "time":1479900702,
    "pkt":"parent",
    "fn":"read",
    "room":3,
    "child0":1,
    "child1":0,
    "child2":0,
    "child3":0,
    "child4":0,
    "child5":0,
    "child6":0,
    "child7":0
}

where the first three values are the same as other packets, and the following are:

Name Value(s) Description
pkt parent This packet details the parent devices
fn read This is reading the parents details
room 0-80 This is the slot that this device is stored in the device table
child0 0-80 The slot number that the first child is stored in. If 0, there is no child stored here
child1 0-80 The slot number that the second child is stored in. If 0, there is no child stored here
child2 0-80 The slot number that the third child is stored in. If 0, there is no child stored here
child3 0-80 The slot number that the fourth child is stored in. If 0, there is no child stored here
child4 0-80 The slot number that the fifth child is stored in. If 0, there is no child stored here
child5 0-80 The slot number that the sixth child is stored in. If 0, there is no child stored here
child6 0-80 The slot number that the seventh child is stored in. If 0, there is no child stored here
child7 0-80 The slot number that the eighth child is stored in. If 0, there is no child stored here

Turning Call for Heat On and Off

It may be necessary for a user to want to stop using Call for Heat. This can be done at the Link level and all Call for Heat intelligence will be paused until it is switched back on. This will result in the parent-children hierarchy remaining in place, but the actual Call for Heat automation to not enact.

Note Be aware that when Call for Heat is switched off, the parent devices will be set to have a schedule to be permanently off and the client should either warn the user, or reimplement the users desired schedule after the command has been received.

To switch Call for Heat off, send the command !F*BP0. To switch Call for Heat On again, send !F*BP1. Using the @C command detailed in “Reading the Call For Heat Setup” can allow you to see if Call for Heat is currently on or off by checking the value of state.

Last updated 10/2/16