mcsxAP & C-Bus

[beerygaz]

Please can someone with more xAP knowledge than I offer some advice here.

I have installed mcsXap and Kevin H's C-Bus gateway. Right now I have control over my C-Bus groups, but in HS they are represented as, what appears to be, standard X-10 lights.

The way the C-bus protocol is implemented I need to send both an "on" and a "level" command to get a light to come on. This poses some challenges when using other tool such as HSTouch or Jon00's web builder. Also, Kevin has mentioned that his gateway supports a xAP message like the following:

class=xapBSC.cmd
...
}
{
Level=100/255
RampRate=120
State=on
}
in order to provide soft up/down functionality.

My question is, what would be the suggested way of adding defaul paramters for Level and RampRate for a device so that a simple "on" command tunrs a C-Bus group on using those defaults. I figure with a lot of virtual devices (for level, ramp rate, etc) and some event scripting I can do this, but it makes ongoing maintenance very tiresome. Is there a more elegant approach?

[Michael McSharry]

Kevin is really the best person to answer the question as he is using this xAP-CBus-HS environment.

It looks as if his C-bus controller is responding to an extended xapbsc schema. mcsXap has no provisions for extensions to the schema for ramp rate so if you want to send this you will need to use script to send xAP message or use the xAP event action. In both cases it will be a result of a change event. In this situation I suggest using the HS Status Change Callback, and if a C-Bus device status is changing then use the mcsXap SendXapMessage script command to send the desired command. This way it will just be a single small script to handle all C-bus commands rather than needing to deal with a large number of events.

For standard commands from Homeseer, mcsXap will do the following:
If you provide a DIM or BRIGHT command with non-zero brightness then mcsXap will send State=ON, Level=brightness/max. For 0 brightness it will send State=OFF.
If you provide a PRESET_DIM_1 command it will send State=ON, Level=brightness%.
If you provide an ON, OFF or IO command it will send State=ON/OFF.

[CouchPotatoe]

Hi Gavin,

Michaels explanation above of the BSC schema implementation within his plugin is very appropriate for the HomeSeer device model. Inparticular the enforced linking of the state on/off to include a state=on whenever the level is non zero is useful in how you personally wish the gateway to behave in that the gateway does not automatically assume this. Nor actually does BSC persay but in most cases this is the desired behaviour.

The reason I don't enforce this is because I use a state=off level=50% for example to allow you to preset a level for when the light is later just turned on using a BSC.cmd message that only includes state=on (no level=). The gateway remembers the last level for every C-Bus group effectively. It also reports this level in any .info or .event message.

In recent firmware builds of the gateway (yours possibly) you can select either style of operation but should you force the gateway to always enforce 'off' when the level is '0' or the converse and enforce level '0' when it is 'off' then you sacrifice both the ability to preset a C-Bus level and also the 'come back on at last brightness' ability. You could of course regain some of this using HomeSeer scripting or your C-Bus config. It's your choice.

The optional inclusion of RampRate= within the BSC schema message is for convenience only, xAP permits such extra 'custom' parameters within schema but you would need to include this parameter via the methods Michael has outlined above as it is not vanilla BSC. HomeSeer does not provide an inbuilt ramp time attribute for it's devices. However all this is easily do-able, and using the scripting route would mean that you would create just one script for all your lights that sets up the outgoing xAPBSC.cmd message appropriately to either include the Ramprate parameter or set other permutations of the state/level parameters as you choose. Conveniently you can wildcard the target= address and just calculate the ID= value from the HS device code to select the specific C-Bus group that you wish to change.

...
target=UKUSA.gateway.c-bus:>
}
output.state.1
{
ID=001A (for group 26)
....

One thing to bear in mind that the C-Bus gateway will respond to any xAPBSC.cmd using the state/level linkage appropriate to how it is configured. This may cause HS to update the device again.

K

[beerygaz]

OK, I've been wrestling with this for a while now and it seems I need a little more clarification on some of the topics. It's clear to me that my approach was unsuitable and that box the mcsxAP plugin and Kevin's gateway are far more felxible and extensible. I just need to learn how to use them properly.

In a simple world, I have an X-10 Lamp device in HS. It has supports on/off and dim/bright. Using the HS web interface, or hsTouch, I can manipulate that device on, off or to a certain dim level.

I'd like to translate that to my C-Bus lighting. I understand that this a slightly more complex approach because of both the flexibility of the interfaces provided as well as the additional parameters that C-Bus can accept.

Michael mentions the "HS Status Change Callback" - I don't really know what this is.

I know I can run a script when a HS device changes status. But that seems to link the event to an individual device. So I would need to write event scripts for each device that changes. That seems inelegant.

Kevin, you mention setting up one script for all my outgoing xAPBSC.cmd messages (so ultimately I could tailor the exact message I wanted) but I'm missing how to tie that script to a whole load of individual HS devices that will be changed via the web interface or hsTouch.

[Michael McSharry]

In a simple world, I have an X-10 Lamp device in HS. It has supports on/off and dim/bright. Using the HS web interface, or hsTouch, I can manipulate that device on, off or to a certain dim level.

I cannot confirm how the c-bus responds, but from what Kevin has indicated in this thread I believe the simple world model works between it and Homeseer. Your light is now something like ^4 rather than M8 since it is an extended rather than native HS device. If you provide on/off/dim commands to ^4 then xAP messages will be sent to the c-bus gateway and the light will correspond to on/off or to the specified dim level. When HS commands ON it sets brightness to 100. When HS commands OFF it sets brightness to 0. When HS commands DIM it sets brightness to some value which is typically 12, 25, etc.

If you want to move beyond the simple world that Homeseer supports natively to one where your lighting control also includes ramp rates then you will need to do this via events or scripts. It is not clear if Homeseer's simple world interface is sufficient for you or not. If it is not then you need to be more specific of what additional control capabilities you will be doing fromm HSTouch that are routed to c-bus.

It is reasonably easy with a small script to send an xAP message and this script would be invoked whenever a HS device status changes. An example can be given, but you need to indicate what you are expecting from an HSTouch action and what changes between one HSTouch button press vs. another HSTouch button press.

[CouchPotatoe]

As Michael says a little more explanation of just what you're trying to achieve will help. Bear in mind that the web style of control does not support the preset/retained levels that the C-Bus xAP gateway does - nor does it support ramp rates so that's not going to be doable from within the HS web interface.

When I alluded to one script then it's because a command to a C-Bus xAP light can be 'addressed' either by inserting the correct name of the light in the target= line in the xAP header or by using the correct ID (group number) in the xAP body - or even both should you wish. The trick here is to recover the name or device code of the device that called your (one) script and to use this to modify what information to send via xAP in the resulting xapbsc.cmd message. Hence one script can send different messages depending on which HomeSeer device called it.

Hence you could have one script that recovered the xAP name/address and placed it in the target= parameter (assuming the xAP name can be recovered eg from devicename or Michael might have a call to recover it from a HS device code). If you do this then the ID= within the xAP body should be ID=* ie a wildcard addressing all lights. As the source is fully qualified still only the one desired light will respond.

Alternatively you could wildcard the target address to
target=UKUSA.gateway.C-Bus:>
in the header, which will address all your C-Bus lights.... and then from the device code that called the script you would calculate an ID which should match your C-Bus group number. This will now again restrict the message to only addressing one light (group).

For example to control group 7 you would provide ID=0007 and for group 12 you would use ID=000C in the xAP body... etc. This approach would require that you align your C-Bus group numbers to the HomeSeer device code eg X1 = C-Bus group 01 , X2 = C-Bus group 02 etc.

K

[CouchPotatoe]

Just to mention Gavin - that if you wish to use the C-Bus gateway in a mode that sending an 'on' command (without a level) will always bring the light on at 100% brightness that could easily be accomodated by a firware tweak but you will lose the ability to use any preset or memory dim functions and some ramps might always start from 100% downwards (like X10). Likewise an off will force the brightness to 0 and a level=0 would force the light to off.

If you were to include a level= parameter the light would still come on at that level but it would be ignored if the state was set to off.

K

[beerygaz]

This is getting me a little closer, thanks guys.

Question 1 @ Kevin
Kevin, how do I determine which HS device called the script. If I create an event where the Trigger is "Device Status Change" and I set the Devie to Any and Status to On, I can run a script every time something is set to "On", work out if it's a light, and send the appropriate xAP command. What I don't know how to do is query which device changed to trigger the script.

Question 2 @ Michael
On my device status page, next to each device created by the plugin I see buttons for "ON/OFF" and a drop down for LEVEL. By default the LEVEL shows 0% for all my devices, and when I hit the "ON" button I see a xAP message sent like this:

output.state
{
state=Off
level=0/255
origin=42
}

This is exactly the same as when I hit the "OFF" button. IT's only when I manually change the level to something other than 0% that I get a light to come on. This doesn't correlte to what Michael said eralier, that hitting "ON" should automatically set the level to 100% at the same time.

[Michael McSharry]

Q1: Look in the HS Help, Using Scripts, Scripting Functions for RegisterStatusChangeCB. There is an examble there as well. At the bottom of the example you would add a test for device code of interest and it satisfied then call the mcsXap scripting function to send an xAP message and you can include anything you wish such as the ramp rate.

The format of the xAP message script interface is
oXap.SendXapMessage(Target, Class, Section, Body, Subaddress, UID)
where
oXap is the mcsXap plugin object which is obtained with something like hs.Plugin("mcsXap")
Body components use chr(1) for the "=" and chr(0) for the LF. For example is you wanted to send STATE=ON, RAMPRATE=20 then the Data string would be
"State" & chr(1) & "On" & chr(0) & "RampRate" & chr(1) & "20"

Q2: Looks as if the brightness level determines the state where 0 = OFF. My memory failed me previously.

[beerygaz]

Had never come across RegisterStatusChangeCB before. Thanks, I now know what you meant by a single script for all my C-Bus/xAP devices, and can write a callback to catch device status changes. Will my CallBack script conflict with direct control? i.e. if a user hits the "off" button on the status page of the web interface, and my CB script sends a customised xAP message with a 30s ramp to 0 at the same time, will I get both actions conflicting?

Secondly:
I've been fiddling with SetDeviceState and SetDeviceValue and neither of then have any effect on my devices - the status changes in HS, but I never see any xAP messages pass through to my xAP gateway.

I then tried ExecX10, lights come on, but still don't get expected results. I need 2 ExecX10 commands, one with an "on" and another with a "dim" command to get a light to come on, hs.ExecX10(")30","on",50) doesn't set my light at C-Bus group 0x1E to 50%.

Is there a reason why SetDeviceValue/SetDeviceStatus don't work as expected? And am correct in using the ExecX10 commands in this instance?

As a footnote, I really appreciate both of you mucking in here and helping a newbie at getting this to work.

[Michael McSharry]

Secondly:
I've been fiddling with SetDeviceState and SetDeviceValue and neither of then have any effect on my devices - the status changes in HS, but I never see any xAP messages pass through to my xAP gateway.

Is there a reason why SetDeviceValue/SetDeviceStatus don't work as expected? And am correct in using the ExecX10 commands in this instance?

The SetDeviceStatus only changes the internal HS status and is not a command to a plugin to perform some action. mcsXap is expecting a ON,OFF,DIM,BRIGHT,PRESET_DIM_1 or an IO command from HS. I thought that the SetDeviceValue will generate an IO command and in this case the DeviceValue parameter from HS is used as the xAP Level= component of the xAPBSC.cmd message and the State= is always ON.

I then tried ExecX10, lights come on, but still don't get expected results. I need 2 ExecX10 commands, one with an "on" and another with a "dim" command to get a light to come on, hs.ExecX10(")30","on",50) doesn't set my light at C-Bus group 0x1E to 50%.

With HS2, there is also a Transmit command that should work similiar to ExecX10. I have never used it, but it is worth a try. Look in the Help under scripting for its syntax. The ExecX10 works with both HS1 and HS2 and that is what I use.

mcsXap has a debug capability and when enabled it will show each command beeing delivered from HS. It will start with SETIO Object= in the debug output. I think this output goes to the HS log, but it not it will be in a .txt file in the \Data subfolder.
[/quote]

Will my CallBack script conflict with direct control? i.e. if a user hits the "off" button on the status page of the web interface, and my CB script sends a customised xAP message with a 30s ramp to 0 at the same time, will I get both actions conflicting?

The Callback is an event notification of what HS is in the process of doing. I forget if the event occurs before or after calling the plugin to perform the action. There is also a similiar callback to plugins (HSEvent) that is called on status as well as several other events such as string changes. A user action will result in an xAP message being sent without the ramp rate parameter. I'm guessing that the script will see the notification after the plugin so mcsXap will have sent an xAP message before the script has a chance to do anyting.

I you make your own custom buttons rather than using the predefined ones from the HS Devices/Status page or other similiar sources then this button action could be use of the hs.SetDeviceStatus and your callback would then be able to service it without mcsXap knowing anything happened.

[CouchPotatoe]

Will my CallBack script conflict with direct control? i.e. if a user hits the "off" button on the status page of the web interface, and my CB script sends a customised xAP message with a 30s ramp to 0 at the same time, will I get both actions conflicting?

Obviously the xAP to C-Bus gateway only reacts based on commands that it receives via xAP. It will immediately react to each command and if this conflicts with a previous command it cancels the previous command and uses the new command. This is really only significant in ramp situations. So if you had a ramp to 0% over 1 minute immediately followed by a ramp to 0% over 30 seconds then the latter would take precedence.

If your light was currently at 80% brightness and you issued an immediate OFF followed by a ramp to 0% over 30 seconds then the actual effect I expect would be the immediate OFF only. This is because the first command is instantly actioned and then you are already at 0% when you receive the second ramp so there is actually nothing to action.

Do however try this on your firmware version Gavin - using xAP Viewer to send the two commands as it is just possible it would work as you hope it might.. due to the level memory feature . You would need a state=on in the ramp command even though it was destined for 0% after the ramp time. There would definitely be a flash off first however from the first off command.

On the still unreleased firmware beta 2 it has potentially changed & works as I described above. This aspect of enforcing a dependency between off/0% and on/non 0% suits some applications but not others. I posted a thread a few months back on the gateway support forum to discuss exactly this topic but received no feedback one way or the other.

K

[beerygaz]

Right, I'm determined to get to the bottom of this as it is starting to inhibit my ability to deploy HSTouch without a load of custom developemtn, and I'm convinced I'm missing something.

mcsxAP has created a load of devices in HS for me. On example being my Study Light as shown.



If I click the "On" button on this device in the web interface. It generates the following 3 xap messages:



The first, which appears to be the command from mcsXap has this content:

xap-header
{
v=13
hop=1
uid=FF.000E:0000
class=xapBSC.Cmd
source=mcs.Xap.ARES
target=UKUSA.gateway.C-Bus:G1E
}
output.state.1
{
State=ON
ID=001E
}
Checksum
{
Length=0172
}

The second, I'm unsure about, but seems to be Kevin's gateway's interpretation of the plugin's command and shows what it intends to send to C-Bus.

xap-header
{
v=13
hop=1
uid=FF.6E0E:0000
class=CB.cmd
source=UKUSA.gateway.HomeVision
}
HVaction
{
cmd=CBApp56 Grp30 Lev0 Ramp0
}

And the third, what I assume is a status or result message of the previous command.

xap-header
{
v=13
hop=1
uid=FF.6E0F:001E
class=xAPBSC.event
source=UKUSA.gateway.C-Bus:G1E
}
output.state
{
state=Off
level=0/255
origin=01
}

From what I can see if mcsXap simply included the LEVEL in the the original command message (normal behaviour for HS is ON implies100% level) then all my woes would be over. Michael, is this an enhancement that could be made to the plugin? It would avoid me having to write a load of code for callback functions, writing my own xap messgaes, etc and just rely on the HS default behaviour.

Kevin, I understand that if I pursue this line of functionality, then every "ON" command would set the level to 100% and override your suggested feature of an ON command restoring the group to a previous "remembered" state.

In addition, setting the level of my Study Ligt via the web interface generates the following message:

xap-header
{
v=13
hop=1
uid=FF.000E:0000
class=xapBSC.Cmd
source=mcs.Xap.ARES
target=UKUSA.gateway.C-Bus:G1E
}
output.state.1
{
Level=50%
State=OFF
ID=001E
}
Checksum
{
Length=0183
}

Again, it may be the intended behavious to set a level without an ON command, but it makes the user interface very counter intuitive given that this is not the default behaviour for other HS Z-Wave or X10 devices.

[Michael McSharry]

The logic that exists within mcsXap is that if HS requests the plugin to set a device to ON or OFF then only the State is sent via mcsXap. If HS requests the plugin to set a device to DIM or BRIGHT (including 0% and 100%) then both State and Level are sent and the State will be the DeviceStatus value currently set by HS.

For a lighting device the level and state have an relationship for those lighting devices that can support a dimming capabilty. The percentage of dimming that consistutes ON is somewhat arbitrary, but some convention can be used.

For another device, such as an irrigation zone, the ON/OFF status indicates if a valve is Open and the Level status indicates the moisture level in the soil. One would not want to set the moisture level to 100% when the valve is turned ON. The State and Level in this case are independent.

The behavior that HS models started with that of X10 devices. Different manufactures have different behaviors and some have presets so even in the narrow category of X10 lighting there area variances.

I do not have any problem with supporting user needs and this typically turns into plugin options or adoption of some conventions. Logic of this nature would be best handled by using information in the device type property to assess if the State and Level properties are correlated. If you propose an approach that is doable then I am willing to try. For example if the device type was set to CBUS or Lighting, for example, then the Level would be included in the xapBSC.cmd message.

[beerygaz]

Michael, I see you point, constructing all messages the way I happen to want them is far to specific to my current application. I'm happy to explore suitable plugin options that present a minimum effort for you.

A check box next to the device in the mcsXap config screen to enable or disable the LEVEL / STATE correlation would work.

I'm happy to even specify that if the Location field on the config screen is set to an arbitrary value such as "Lighting" then set STATE to ON when LEVEL is greater than 0.

I could prefix prefix my device names with some indicator for this custom correlation even.

Thanks very much for offering to try and meet my specific needs.