New Scripting command to replace CAPI

[jon00]

In Homeseer 2, scripters had a simple method to control devices using hs.ExecX10 and hs.Transmit commands. HST removed the functionality in Homeseer 3 and replaced it with CAPI control. This requires far more coding and is much harder/complex for the occasional scripter.

Do you think that HST should provide a new scripting command to control devices in HS3? If you agree, please post ideas how this would be implemented bearing in mind that there is now no standard for On, Off etc and is plugin dependant.

[mrhappy]

Parts of me think that having a value change callback in a plugin should be mandatory rather than optional, perhaps even a separate function to handle value changes only that come from your plugin rather than needing to filter out irrelevant value changes. That way the only thing an end user needs to do is hs.setdevicevalue and the device will then control, I know some plugins do this already and some don't.

For an occasional scripter I think hs.execX10("A1","On") and hs.setdevicevalue("A1", 100) are really here nor there as long as it is explained that 100 is on, 0 is off etc somewhere in the documentation.

That thought might not make me particularly popular though...and there is probably something I am overlooking.

[tenholde]

Mrhappy,

Agree with you, except that it requires you to know what value each plugin writer has determined should mean ON and OFF.

HS has added the ability for plugin writers to define special CAPI control entries for ON OFF DIM, but I'm not sure how many plugin developers have implemented this so far. mcsSprinklers does not appear to implement such.

see: CAPIGetSingleControlByUse

here: http://homeseer.com/support/homeseer...lp/default.htm


The following vb.net code will get the CAPIControl oject to turn a device ON:



Dim objCAPIControl As CAPIControl
Dim dvRef as Integer

dvRef = hs.GetDeviceRefByName("My Device")
objCAPIControl = hs.CAPIGetSingleControlByUse(dvRef,ePairControlUse._On)
If objCAPIControl IsNot Nothing Then
hs.CAPIControlHandler(objCAPIControl)
End If




tenholde

[wes]

or at least make some decent documentation with examples.

I've been using HS since 2001 or so, never had the problems i've had in the last couple days since upgrading.
I would consider myself an intermediate programmer, self taught on HS and vbscript, which worked it way into javascript and PHP.

today, I've spent about 3 hours trying to make a light dim from a script, yes 3 HOURS. and the only way if found to do it was having a script that ran through all of the available commands till it found one that matched, and then run that. and it only works in a vb script, so trying to run it from a web page is still a no go.

i've been able to find a one line command
hs.CAPIControlHandler(hs.CAPIGetSingleControl(dev,true ,"on",false,true))

which i can turn things "off" with, or "on to last value" (not even on to 100%)
but "Dim 50%" doesn't work, unless i run test script that cycles through everything, and picks that label from the list of available commands.

============
your upgrade instructions are laughable, and create a sense of false hope that it will be easy.
they should be
1. in HS2 document all of your events and devices (write down, print, print to pdf)
2. tell your friends and family goodbye, make sure the pets have food for a few days.
3. start HS3 from scratch and manually create everything.

[stevea]

I've expressed my opinion here before. I've not purchased or downloaded HS3 primarily because of what seems to be nonsensical choices made in its design. First and foremost is the control of devices. A cursory examination of the existing scripts in EITHER the provided samples in HS2 or in the scripts library here (on HST's own board) shows that the most often used methods are those to control devices. And yet, the HS3 design decided to completely abandon this simple interface and make it nearly impossible. This is just plain bad engineering. No thought for backwards compatibility, nor any consideration for their users.

I've managed large teams of engineers in software development jobs, including new versions of existing products. The approach taken here would have never been taken in ANY of the projects I've seen in 35 years.

Steve

[jon00]

The poll results look pretty conclusive at the moment!

If HST resurrected hs.Transmit, I was thinking that there should be an override method to set the on,off and dim values, something like:

SetTransmit(ByVal DeviceRef As Integer, ByVal OnVal As Integer, _
ByVal OffVal As Integer, Optional ByVal DimLowerVal As Integer, _
Optional ByVal DimUpperVal As Integer)

And another to clear:

ClearTransmit(ByVal DeviceRef As Integer)

That way, it would make it much easier to use if a plugin/script did not provide the necessary functionality.

[mrhappy]

Just thinking about my idea above, I guess it depends on what people are using hs.execX10/hs.transmit. If they are using it to control X10/ZWave then perhaps it is feasible for those plugins to have functions to replicate hs.execX10. If they are using virtual devices then I can't see why hs.execX10 could not be replaced with hs.setdevicevalue (as per above, it is explained what is on/off) relatively easily.

Some sort of function like;

hs.PluginPropertySet("X10/TI103", "", "ExecX10", New Object() {"Dim",100,0,0})

?

[Rick Tinker]

I've expressed my opinion here before. I've not purchased or downloaded HS3 primarily because of what seems to be nonsensical choices made in its design. First and foremost is the control of devices. A cursory examination of the existing scripts in EITHER the provided samples in HS2 or in the scripts library here (on HST's own board) shows that the most often used methods are those to control devices. And yet, the HS3 design decided to completely abandon this simple interface and make it nearly impossible. This is just plain bad engineering. No thought for backwards compatibility, nor any consideration for their users.

I've managed large teams of engineers in software development jobs, including new versions of existing products. The approach taken here would have never been taken in ANY of the projects I've seen in 35 years.

Don't sugar coat it now, tell us what you really think.

And of course, it is beyond you to believe that we may very well have had good reason to make the changes that we made.

Anyway...

If a device is not owned by a plug-in, then any of the value, string, or last change commands can be used. These are essentially unchanged from HS2 to HS3 - "essentially" because integer is now a double (people wanted decimal values, so we listened) and because the CONFUSING matter of the device status is gone. So now, instead of having to remember the ON is a status of 2, OFF is a status of 3, and DIM is a status AND set the value, it is just one value.

If a device is owned by a plug-in, then you use CAPI, the device Control API. The purpose of CAPI is for the fact that not every device maps to the 0-100 of an X-10 light, which is what the old status was born from. I understand that some people just hate change, and there is an apparent lack of examples on our part for using CAPI for something other than On/Off, so I will post some examples here shortly. In a nutshell, you get the CAPI Control options from a device - you can get all of them or you can get a specific one if you know that the plug-in author set the ControlUse property, which is how the On, Off, and Dim values are indicated even when the labels are not On/Off/Dim. Once you find the control you are looking for, you feed that to CAPIControlHandler and you're done - the plug-in is notified that you want something to happen, the plug-in does it, and if necessary the plug-in will then update the device to reflect the new status.

Examples will come soon.

[tenholde]

I think we need a campaign to encourage plugin writers to provide the ControlUse capability, and advertise to script writers that it exists. Query: do all of the HS provided plugins implement ControlUse ? Would be easier to script X10 stuff if that plugin did.

Seems like the simple solution of the ON/OFF frustration, within the new CAPI framework.

However, would it really hurt to provide simple scripting commands (like DeviceSetON, DeviceSetOFF) that would use the ControlUse interface if it is defined for a Device? Seems like everyone is writing their own similar functions, that then must be included in each script they write.

Another thing that would be worthwhile is the ability to provide a GlobalScript script that would be always loaded and the functions within that script available for all scripts. That way, it would be easy for a script writer to write a few global functions that wrap the CAPI stuff and use them from all of their scripts. Perhaps there is already a way to do this?

tenholde

[Rick Tinker]

OK - Script enclosed which provides a couple of ways of controlling a device using its device name.

One method allows you to provide the ControlUse value (On/Off/Dim) and the other allows you to provide a label or value and it will find the CAPIControl object.

If the ControlUse is Dim, note that you need to provide the dim value as well because that control could be a range (1 to 98 for example) and so you need to tell it which value within the range to use. The script takes care of that.

[jon00]

Rick,

Thanks for your work on this. One thing I'm sure people are thinking, why not just add this internally to HS3 and add them as 2 new scripting commands so it is available to all?

[sparkman]

Rick,

Thanks for your work on this. One thing I'm sure people are thinking, why not just add this internally to HS3 and add them as 2 new scripting commands so it is available to all?

That's exactly what I was thinking too. I appreciate the scripts provided, and do a lot of scripting myself so I'm ok, but if you're trying to make the product as user-friendly as possible, I don't understand why you would not built those functions in.

Cheers
Al

[Rick Tinker]

Rick,

Thanks for your work on this. One thing I'm sure people are thinking, why not just add this internally to HS3 and add them as 2 new scripting commands so it is available to all?

Because people will try using "Dim, 72" to set a thermostat to 72 degrees, or they'll look for 72.3 degrees when the control options are 72.2 or 72.4, or they'll ask why "On" did not work for the device that was set up with a control label of "Turn On". If you have a reason that you need to use a script to control a device, then you should know enough to create and maintain that script. Scripting is NOT intended to be for the consumer, it is not intended to be intuitive - it is for technical people who want to do technical things. If people have to learn how to use the commands properly by figuring out what is going wrong, then they will learn the commands better. If I provided those script commands and they did not work with the values the user thought would work, they would come back to US to answer why it does not work rather than putting another log statement in there to see what CAPIControls are returned and figure out what is wrong. So much about CAPI is based upon how the device is set up, and we do not have the resources to help people figure out why they could not control the device the way they thought it should be. With the commands to get the controls, the script author can examine the controls to help resolve issues - for example, a Z-Wave device has a value of 99 for full on, and 255 for on-last-level. Even though one has a control use of On and the other On_Alternate, what if I did not make the label different? What if I made them both have "On" as a label so that there were two controls for on? The user who is going strictly by the label would have to examine them closely and figure out which one they want, versus the one using the ControlUse would not, but there is NOTHING stopping some other plug-in owned device from having duplicate or similar labels that cannot use the ControlUse parameter. Another example - if the script is not looking for an exact label, and is looking for the word "heat", and the device is a thermostat which has "Heat" and "Auxiliary Heat", that device has no ControlUse set for any of the controls because they are only for on/off/dim use. The user would have to look at the controls and rather than looking for the word heat, realize that they need to look for an exact match of heat. Again, since we do not set the labels, we cannot control this and guarantee a good result every time.

[Rick Tinker]

That's exactly what I was thinking too. I appreciate the scripts provided, and do a lot of scripting myself so I'm ok, but if you're trying to make the product as user-friendly as possible, I don't understand why you would not built those functions in.

Cheers
Al

Scripting never was, and never will be intended to be "user-friendly". If it were, then I would have issue with a LOT of the commands in the language itself before I even begin to tackle the HomeSeer commands.

To twist the words of Dave Barry, "You Have to be a Real Stud Hombre Cybermuffin to Handle Scripting"

[megatron2]

I vote that HS should do whatever Jon needs, so that he can port his Web Page (QuickView) Builder script to HS3. I cannot see me ever adopting HS3 until I have this... and I already paid for the upgrade. Fingers crossed. What is the return policy for upgrades that have never been activated?