Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======Vera UI7======

In the UI7 version of Vera software they switched to a new connection protocol. We still support the older protocol and it still works for the most part so if you are happy with the functioning of your system there is no need to update. Support for the newer UI7 protocol is currently in Beta testing as of XTension version 9.3.11. It seems to be the policy of Vera that they will not fix bugs in the older protocol nor are they going to add support in it for the newer devices or features. This means that if you have a newer device like some of the newer thermostats, or a device with more advanced features than were supported in the older version you will need to update to the new interface in order to use them. If you’re starting a new Vera connection you should start with the Beta version and only fall back if you have a problem.

=====Converting an existing Vera Interface=====
**It is important that you follow these instructions to convert an existing Vera install to the new protocol!** The new system uses different addressing and device type settings than the old system and you must properly convert your units. A backup of your database is made before the process begins (though you may wish to manually zip up a copy of your database just in case as well) so you can return to the older interface by putting that back if there are problems. As of XTension 9.3.11 there is no way to convert your units back to the old protocol other than doing a lot of manual editing or putting back the previous database.

To convert an existing Vera connection open the Interfaces window from the Windows menu and double click your current Vera interface to edit it.

Change the Device Type popup from “Vera” to “Vera UI7” 

You will be presented with a conversion window listing all the units associated with that Vera interface. The columns will show the current device type and current address, as well as the new device type and the new address. Anything that is unknown or unusual that may not convert properly should have an asterisk denoting a potential problem. You’ll want to test any devices showing that to make sure they are working properly.

The only changes that are made to the units are the device type popup selection and the address.

At this point you can cancel the conversion or you can click the Convert button to make the changes. 

Your Vera interface will be disabled if it’s currently running, a database backup will be made automatically and your units will be converted to the new settings and the database saved. Once the process is completely you can close the window if it didn’t close automatically and re-enable your vera interface which will connect via the new protocol.

----
=====Thermostat Changes=====
===Combined Setpoint===
Thermostat handling has changed between UI5 and UI7. It seems that the Vera interfaces no longer support dual setpoint thermostats but that they do still accept setpoints for the thermostats that support it. I can’t obviously see how I can tell from the data that they are sending me if the thermostat you have supports dual setpoints or not so for the moment I am creating both the original **heat setpoint** and **cool setpoint** units along with the newer **combined setpoint** unit.

As of XTension version 9.3.10 there is a new Combined Setpoint control you can add to views and web interfaces to support this setting better if you wish to use it.

On my thermostat, which does support the dual setpoints, I can still use the combined setpoint unit to set the temperature, but it seems to set the heat and cool setpoints some minimum range around the combined setpoint rather than setting the currently active setpoint to the actual value of the combined setpoint unit. This may be an attempt to simulate an automatic switchover mode for thermostats that don’t actually support that. Perhaps the vera will attempt to switch between heat and cool modes on those thermostats. I don’t know. Please experiment with this and decide which unit functions best for your thermostat and application.

===Energy Savings Mode===
The UI7 interface will create an Energy Savings mode unit to control the turning on and off of this setting. Not all thermostats support this feature but I cannot immediately see in the configuration data from the Vera how I can tell if the thermostat in question does or not so for the moment I am creating this unit for all thermostats. If yours doesn’t support it then you can ignore this unit. 

My thermostat does not appear to support this function so I have not been able to test it. If this is something you wish to use please try it out and let me know if the command it properly sent to the thermostat and also if the unit in XTension follows changes that you make manually at the thermostat or via the Vera interface directly.

There is some confusion in the protocol about where the info about energy savings mode will actually show up and there appear to be 2 different ways to potentially set it. This is the most obvious way so this is what I implemented, but there is also a Mode setting that references it, see below.

===New Modes===
The new protocol supports several new HVAC modes. Assuming your thermostat supports any of these you can set the modes value in XTension to the interface value corresponding to them like this:

^Mode Unit Value^Description^
|0|Off|
|1|Heat|
|2|Cool|
|3|Auto Changeover|
|4|Aux Heat|
|5|Economy Heat|
|6|Emergency Heat|
|7|Aux Cool|
|8|Economy Heat|
|9|Building Protection|
|10| Energy Savings Mode|

===Fan State===
The Fan State mode seems to be gone. You can still use the fan mode unit to set the fan to auto, on or periodic on as before, but there is no longer a separate unit that tells you if the fan is on or off. The thermostat controls will still ask you to specify a fan state unit, but you can leave it set to None for the moment. I may repurpose that portion of the display for some other newer more relevant information soon.

===Fan Speed===
The new interface also supports a new “Fan Speed” unit. I’ve never seen a thermostat or a furnace that let you directly control this so I don’t know exactly what it really means. This is not implemented as of XTension 9.3.11. I will implement this eventually for completeness but if anyone can use this sooner rather than later please let me know and I’ll bump it up the list.

----
=====IR Devices=====
XTension now can support the IR Device type. There are IR sending devices that the Vera supports. If you create a new unit and set the device type to IR Device you can then enter a Pronto Code to be sent when the unit turns on or off. You can look up pronto codes for whatever devices you want to control on the internet. 

===Addressing the IR devices===
There is a single “root” address associated with the IR device. XTension will create automatically a single unit with that address for you when it detects that you have an IR device attached to the Vera. You can create any number of other IR devices so that you can send any number of pronto codes by creating new units and giving them the same root address and a decimal and then incrementing numbers after that. So if the root device was at address “104” you could create as many units as you like addressed as “104.1”, “104.2”, “104.3” and so forth. 

----
=====Security Devices=====
Security Devices create a root device in XTension which corresponds to the “tripped” value. Versions of XTension prior to 9.4.6 also created an “armed” unit for each security unit that would reflect the state of the armed setting in the Vera. As of build 9.4.6 this unit is no longer automatically created since it was mostly just noise that doesn’t affect your XTension handling of the tripped status. While the Armed unit is no longer automatically created the information is still sent to XTension. If you need the armed handling in XTension then you can now manually create a new unit, assign it to the proper Vera interface and set it’s device type to “Armed” and it’s address to the same number as the corresponding Tripped unit. Save the unit and it will now follow the Armed state of the security device in the Vera.

If you don’t wish to have these extra units in your database any longer you can delete them after the 9.4.6 update. 

Note that the Tripped units in XTension will receive updates to their state regardless of the setting of the Armed unit. Even disarmed units will still report to XTension. It is only within the Vera that scene and alarm status changes check for the Armed state before performing an action.

If your security device has a tripped date in it, the last activity date of the unit that is created for it will be the date and time when the trip occurred and not the time when XTension received the command. There can be a short delay between the sensor tripping and XTension receiving the command and in this case the dates will match up in both places now.

----
=====Generic Sensors=====
Devices that the vera treats as generic sensors should now send their data properly to XTension. XTension should also be able to better ignore some incorrectly created generic sensors that the Vera still sometimes creates but which hold no values. If you have such you can try deleting them after converting to the new interface and they should stay deleted though upon startup you will see a note in the log about “some unit name was ignored as it has no current value”

----
=====Vera “Meta” Units====
The vera maintains several counts for it’s own UI display and those are now available in XTension units. Upon starting up the new interface you’ll see the following units created: 

^Name^Address^Description^
|Vera House Mode|MODE|The house mode, normal values are Home, Away, Night, Vacation. You can also change the house mode of the vera by setting this value to an integer 1, 2, 3 or 4|
|Vera Lights On Count|LIGHTSON|The number of lights the Vera has turned on|
|Vera Lights Off Count|LIGHTSOFF|The number of lights the Vera has turned off|
|Vera Failed Device Count|FAILED|The count of devices which are not responding|
|Vera Tripped Sensor Count|TRIPPED|The count of tripped security sensors|
|Vera Not Tripped Sensor Count|NOTTRIPPED|The count of safe security sensors|
|Vera Locked Door Count|LOCKED|The count of all locked doors|
|Vera UnLocked Door Count|UNLOCKED|The count of any unlocked doors|

Once the units are created you can change the names of them to anything that makes sense to you just don’t change the address or device type.

----
=====New Vera Scripting Commands=====

You can tell your vera interface to do the following things directly. Note that the names of the commands are always followed by parentheses in AppleScript even if there is no value to pass to the command. Without them they will not work.

===Delete Device By ID===

It is sometimes useful to be able to tell the vera to delete a device directly if it’s not showing up properly in their interface. To do so from XTension you could do this from the Command Line to begin a device deletion on the Vera. You should not use this for normal deletions, use the regular Vera interface for that so that the devices can be properly unlinked from the network, this is for devices that are not responding or that otherwise won’t delete from the regular interface. This may not be able to delete some errant vera devices either. **warning** if you specify the wrong ID number then some other device will be deleted from the Vera. If you specify the address of one of the interfaces (like 1 for the default ZWave interface) it could delete your entire network or other horrible thing requiring a reload of the Vera from last backup. Don’t put this into a script for automatic use, make sure you’re passing the correct ID number for the errant device you wish to delete.

<code>
tell xInterface “name of your Vera interface” to deleteDeviceById( 103)
</code>

===Delete Device===

Just like the Delete Device By ID command above with all the same warnings but sent directly to an XTension unit and not using the ID.

<code>
tell xUnit “name of Unit” to deleteDevice()
</code>

this will not delete the unit in XTension, you’ll have to do that separately after the Vera finishes it’s processing. If not successful the unit may just be re-created in XTension when it reconnects to the Vera.

===Reconfigure===

In UI7 there is no longer a Heal Network command. However you can tell individual units to reconfigure themselves which will also rediscover their neighbors and update routing information. You can reconfigure a device by telling the unit directly, or you can do so by ID by telling the interface.

<code>
tell xInterface “name of your Vera interface” to reconfigure( 103)
</code>

or by telling the unit itself:

<code>
tell xUnit “name of the unit” to reconfigure()
</code>

In which case the ID number is not necessary, but the parans at the end of the command name are necessary.

===Update Neighbor Nodes===

If a unit isn’t responding or isn’t reliable you may be able to fix that by updating the neighbor nodes of it and/or it’s nearby units. You can do this by telling the unit to updateNeighbors.

<code>
tell xUnit “name of the unit” to updateNeighbors()
</code>

This is not something you necessarily want to script to automatically happen as the network may be unavailable while the update is happening and it can take several minutes to complete for a single unit. Use this for fixing problems more than regular maintenance.

===Save Status Data===

This is a debugging aide. If you have a device that is not displaying the proper values or that I otherwise need to see the low level data for you can tell the unit to do this directly (see below) or do it by ID by telling the interface. After issuing this command a file will be created on your desktop that contains the JSON data for this device. Please email me that file along with any other data that might help me understand what I’m looking at and what you wish it to do.

<code>
tell xInterface “name of your Vera interface” to saveStatusData( 103)
</code>

or direct to the unit like:

<code>
tell xUnit “name of unit” to saveStatusData()
</code>


===Send Command===
This command can be used to send any command to a unit that the Vera supports. Sometimes unusual or UPnP devices require a service id, action name and variables that are not known until you connect to the device. There will be a “custom” device type that will let you associate XTension verbs with the proper services and actions. That device type is not implemented as of this beta version. Even so it may be useful to be able to tell any unit to do anything that it supports. You’ll have to know what the proper commands are in order to use this command. These are not necessary for any standard or well known unit linked to your Vera, but only new and novel things that we don’t support support yet.

<code>
tell xUnit “name of unit” to sendCommand( serviceID, action, “variableName=variableValue”, “variableName=variableValue”, ...)
</code>

the first value is the service name, something like "urn:micasaverde-com:serviceId:DoorLock1”, the second value is the name of the action, something like: “SetTarget” the next variables are name=value pairs for as many variables as also need to be sent to the command. For example: “newTargetValue=0”


note that capitalization counts in all these values.

An example that would turn on a light:
<code>
tell xUnit “name of unit” to sendCommand( "urn:upnp-org:serviceId:SwitchPower1”, “SetTarget”, “newTargetValue=1”)
</code>

===Move Up===
This is for window coverings and is the same as turning ON the unit that normally controls them so should not be necessary to call directly.

<code>
tell xUnit “name of unit” to moveUp()
</code>

===Move Down===
This is for window coverings and is the same as turning OFF the unit that normally controls them so should be be necessary to call directly.

<code>
tell xUnit “name of unit” to moveDown()
</code>

===Stop===
This is for window coverings and is the same as using the regular XTension verb **Stop “name of unit”** or using the contextual menu handler for a window covering unit. It should not be necessary to call directly, but you can if you wish.

<code>
tell xUnit “name of unit” to stop()
</code>

===Clear KWH===
This is for KWH Measurement units and is the same as just telling the unit to turn off. That will reset the KWH reading to 0. You should not have to call this directly but you can if you wish. There is also a contextual menu option to clear a KWH devices value back to 0. Note that not all Vera devices that support sending this value support clearing the value. If your value does not go to 0 after sending this command then the device won’t let you reset it.

===Set Data===
The setData command is sent to a specific unit. It is for setting ZWave parameters or variables and is potentially dangerous. Because every brand and model of device is different you’ll have to know exactly what you need to send in order to set the data correctly. Sending incorrect data or data meant for a different device could brick the dimmer or cause any number of kinds of malfunctions. Most manufacturers print the parameter data in their user manuals. but not all of them.

This could be used to set the local ramp rate of a dimmer switch, or an of the other configurable options in a device. For the new Home Seer HS-WD200+ dimmer this can be used to change the light color on an individual LED basis. 

<code>
tell xUnit “name of unit” to setData( parameterNumber, byteCount, value)
</code>

If the device is a battery operated device then the change will be sent by the Vera when the device next wakes up, if it’s a routing device then the change will be sent immediately. Most parameters i’ve seen are single bytes. The value can be a single integer number from 0 to 255 or might be a longer string of data depending on the parameter. If you have the data in hex instead of an integer you can send a string starting with a letter “x” for example “xFF” for 255.

See the supported module section or your user manual for what parameters are available.

----
=====Central Scene Support=====
This is one of the more exciting features you will get access to with the new interface. Devices that support “central scene” reporting will send you almost instant updates of local changes to the switch, you will not have to wait for a poll to take place sometime later to discover the device was changed manually.

More importantly this lets you attach functions to the on and off click, as well as any of the special clicks that newer switches support. The new HomeSeer switches support many “gestures” and this lets you trap them all. They include single click, double click, triple click and click and hold. There are also newer scene controllers which support Central Scene support and which function much better than the older scene controllers that required you to create a scene in the Vera to correspond to the Scene in XTension. All actions at the switch can be captured and processed in the on centralScene handler in the corresponding units ON script.

To capture a central scene event create this handler in the ON script of the Unit:

<code>
on centralScene( theButton, theGesture)

    write log “central scene processing for “ & thisUnit & “ theButton=“ & theButton & “ theGesture=“ & theGesture

end centralScene
</code>

What values are sent in theButton and theGesture will be specific to the type of device that you are connecting from so the first thing you should do is to use the log line above to capture what values are sent and then use those to parse out later what you want to do for each gesture to each button. On the Home Seer switches I have a 1 is sent when I click the ON paddle and a 2 is sent when I click the off paddle. The Gesture values are 1 for a single click, 2 for a double click, 3 for a triple click etc. 

With the Home Seer switches no local load level changes happen for the double or triple clicks so if you want the local load to change value when using those you’ll have to add that control to your script as well.

Checking for the button value and the single click gesture should replace checking for the [[dictionary:unitinformation:incoming|incoming]] value and waiting for the value to change and run the ON or OFF script. The central scene information comes into XTension almost immediately but the value change at the local device will still take a few more seconds to arrive as the device has to be polled.

Note that with a dimmable switch the poll may return an interim value for the load level and not the final value. The final value should show up soon, but there is no way to make sure I’m getting back the final target level rather than some value in the middle of the slow fade. This is another reason that you should use the central scene event and not just the ON script as it may run 2 or 3 times over a long slow fade.

As of XTension 9.4.6 another unit device type was added for “Scene Controller” if you have devices like the Aeotech WallMote or other central scene capable scene controllers they will now show up properly and you can trap their button pushes in the same on centralScene handler as above. Specifically for the WallMote you can also check the new “ignore gesture” checkbox in the edit unit dialog. The gesture information needs to be gotten from the Vera in a separate step and can make the handling of the button action take longer. In the case of the wallmote it sends a different button value for each action anyway and so the gesture information is not needed. The Home Seer switches do not do this so they require the gesture information as well if you wish to know if the paddle was double clicked or cilck and held or any other supported gesture.


----
=====New Unit Properties=====
===LastPollSuccess===
The units will now have a unit property updated fairly often entitled “LastPollSuccess” which will show the last time the unit properly responded to a poll from the Vera.

===ConsecutivePollFails===
If the unit is offline it will also have this count available showing how many polls it has failed to reply to.

===Poll Rating===
If the device supports polling it may also have a “PollRating” property. This will be a 5 for a device that returns all polls and reduce to 0 for a device that is returning no polls. It can be used as a reliability indicator for certain problematic units.

----
=====Power Metering Changes=====
The new user interface does not record continual values of 0 for metering capable devices that are off or that just aren’t using any power. You may need to change your plot type in [[xtension_manual:editunitxtdb|XTdb]] to discrete rather than smooth to display it properly.

The Watts Usage units display the instantaneous measurement of power usage when the value is sent. With the new protocol you can optionally also capture the Average usage since the last measurement as well as the peak usage since the last measurement. These units are not created automatically so if you wish to capture this data you will have to create the unit yourself.

Create a new unit set to the Vera interface, select the device type of Watts Measurement. Set the device type to dimmable. Set the address to the same number as the automatically created unit for that device but add the suffix “.AVERAGE” or “.PEAK” to the end. After saving the unit it will begin to receive those values as soon as the next reading is sent from the device. You can create both an average and a peak unit for any given Vera watts usage device or just one or the other.

----
=====Door Locks=====
As before a unit is created for each Pin code entered into the lock. When the door is unlocked via a pin code that pin code unit will receive an ON and it’s ON script will run. Note that like the previous version there is no guarantee of the order that the commands will be received in but you will get the change of state for the door lock unit as well as the ON for the pin code unit. 

===Lock Button===
If the lock button is used to lock the door you will receive both a change of state to locked of the parent lock unit as well as a call to a handler in the ON script of that unit called “lockButton()” so you know the door was locked from the outside rather than manually from the inside or via a key. To receive this event create an ON script for the lock unit and create the handler like:

<code>
on lockButton()
  write log “the door was locked via the lock button”
end lockButton
</code>

===Lock Failure===
If the lock throws an error instead of properly locking or unlocking, such as a jam, it will execute a handler called “lockFailure()” in the On script for the lock like:

<code>
on lockFailure()
  write log “the door lock is jammed!” color red
end locFailure
</code>

Note that this is hard to properly test, if you receive this event please let me know if it properly cleared after the jam was cleared or what happened.

===User Code Locked===
Depending on your lock hardware you may also be able to receive events when a user code is used to lock a door instead of unlocking it. This might be useful as you’re leaving to execute your alarm setup scripts or otherwise setup the house for a specific mode. This does not appear to be supported for all locks please test.

If this works for your device then when the door is locked via a pin code that pin code unit will receive an OFF command and the OFF script will run.

----
=====on JSON received=====
The structure of the JSON being sent in this version is completely different than the previous version. No code written for the direct json handlers will work with this build, but then you shouldn’t need it for most things. This beta version will not call any JSON handling code at all so there is no reason to delete it yet. If you find there are things you were pulling out of the JSON data directly that are not properly handled in this new protocol version please send me details of it and we will make sure it’s going where it needs to go.

----
=====Other Info and Thoughts=====
The new protocol is more immune to the extra units that often got created alongside the real units with the old protocol. For example I have a number of devices that created a Light sensor along with the watts sensor even though the device had no such sensor capability. If you’re converting from an old protocol version please try deleting such units and see if they stay deleted.
Mac Home Automation

User Tools

Site Tools

Page Tools
