Alarm Panels and interface standardization

Javier,
Now that you’ve got a good start on the DSC Panel code at:

http://code.mios.com/trac/mios_dscalarmpanel

I can see that we need to focus on standardizing the “core” interface (Arm/Disarm/Stay/Breach/Force etc) for all Alarm Panels so that we can get UI support from the various Control Points.

That was my intent when I created S_AlarmPartition1.xml, to have it evolve and then “included” as a standard component of MiOS so that we all had a contract to code against:

http://code.mios.com/trac/mios_paradox-alarm/browser/S_AlarmPartition1.xml

from your codebase, it looks like you’re building a DSC-specific version of this:

http://code.mios.com/trac/mios_dscalarmpanel/browser/S_DscAlarmPartition.xml

It’s important that we standardize this interface, similar to how interface defn’s have been standardized for Lighting, Heating, AV (etc)… esp if we ever want to encourage the Control Point vendors to provide Alarm Panel support in their UI’s (SQRemote, iVera, etc)

Thoughts?

[quote=“guessed, post:1, topic:166000”]It’s important that we standardize this interface, similar to how interface defn’s have been standardized for Lighting, Heating, AV (etc)… esp if we ever want to encourage the Control Point vendors to provide Alarm Panel support in their UI’s (SQRemote, iVera, etc)

Thoughts?[/quote]

yes, obviously standardization is a goal. to be honest, i didn’t read your previous work while writing the DSC one. after a quick glance, i see a few important differences on how both panels manage partitions, or maybe it’s mostly a vocabulary thing… i don’t know yet.

can you share some docs on the paradox API? to see if there are enough common points, or if the differences are too big.

another option would be to define a common S_xxxx and put the specifics on a separate S_yyyy

about other device types, that was easier because we just use the S_zzzz files from the UPnP Forum webpage.

This is the ASCII Programming guide:

http://www.elektro-mahl.cz/dokumenty/DIGIPLEX/DIGIPLEX-ASCII-EP00-eng.pdf
about other device types, that was easier because we just use the S_zzzz files from the UPnP Forum webpage.

For lighting, perhaps, but you have a lot of org.micasaverde type ones as well (including the entire AV Suite)

Javier,
Have you gotten any further to which bits can be standardized?

It seems like the following are common concepts, although the names differ across panel makers:

[b]Stay(pin)[/b] - At home arming, with a PIN (Motion Sensors excluded, Doors, Windows armed)
[b]Stay()[/b] - "OneTouch" or "Quick" at home mode, no PIN required
[b]Arm(pin)[/b] - Regular arming with a PIN
[b]Arm()[/b] - "OneTouch" or "Quick" arming mode, no PIN required
[b]Disarm(pin)[/b] - Disarm the house with a PIN
[b]Fire[/b]
[b]Emergency[/b]
[b]Medical[/b]

Most of these would be some sort of “request” method, where the event is sent off async and may fail. Similar to how you have [tt]SetLoadLevel[/tt] for dimmers (etc)

Whilst you’re looking at standardizing that, can you also add:

[tt] D_WindowSensor1.xml[/tt]

similar to how [tt]D_DoorSensor1.xml[/tt] “mirrors” the [tt]D_MotionSensor1.xml[/tt]?

This would allow anyone coding a Panel to differentiate between Doors, Windows and real Motion sensor events… if their Alarm Panel is self-describing, or provide a way for the user to Manually indicate which zone is what type (as you’ve done in your DSC Codebase)

Separately, the UI could eventually have a distinct Icon for each (Motion, Door or Window) which would make them a little easier to differentiate from the “running man” in UI4.

Thoughts Javier? We really need to standardize this stuff so that the Control Points can add Support. Otherwise it’ll be a UI4 “UI only” type of implementation.

Hi guys, has there been any progress or movement on this? Is there anything I can do to help out?

Due to the aforementioned lack of consistency and no support in the iVera and other iphone based UIs, I’ve had to code the link to my DSC alarm panel (via a TL-150 IP interface card, not the serial interface) using Lua code embedded in a couple of scenes - not something thats easily packageable or distributable to other users if they’re interested in interfacing that way (aside from maybe posting the code fragments on the forum). I also currently have no way of showing the alarm panels status in iVera.

One thing to point out is that not all alarm installations use partitions - the UIs really need to support arming/disarming of the whole system as well.

@macca, we’ve not heard back from Javier for this effort, but @futzle has made excellent progress in implementing the existing Alarm Partition stuff. In cases where the alarm system is small, the implementation of this would only have “one partition” (which is the whole alarm partition) so the model still works.

You can see the efforts on that Panel here:
http://forum.micasaverde.com/index.php?topic=4060.0

There were some adaptations of the interface that I had outlined, in order to expose the “last user”, and it’s on my ToDo to add the functionality to the core, potentially as the baseline interfaces for folks to use, but I wanted Javier’s feedback first since he’s implementing another Panel and it might have a “different” featureset.

Thanks. I have the IT100 as well as the TL150, so I’m trying to port Javier’s code over to the “standard” interface, as well as implement the TL150 code to the standard i’d mentioned earlier.

The thing thats got me a little puzzled is why we need both an Armed and a Disarmed variable on the interface - isnt one the inverse of the other, so one variable would be sufficient? I think it would be more useful to have 2 different variables - status (armed/disarmed/trouble) and detail (armed=stay/away, disarmed=blank or have some other info if applicable, trouble=tamper,low battery,comms error).

Yes, Armed and Disarmed were deliberate. It was done mostly so that “dumb” clients could chose which one that wanted to display without additional negation logic.

It’s similar to why there’s a Armed (which represents traditional “Armed” or “StayArmed” type events) and a separate one for StayArmed, for those that want to track the finer-level status.

Once you get beyond a core of status’s you’ll find that the Panels all deviate on what they support, or at least what they support through API. I expect that there will be a “core” of Alarm functions, and that things like “Tamper” (etc) will go either as Scene events, specific to that AP, or they’ll end up with AP-specific status’s.

Earlier versions of Vera also didn’t give great visualizations for Enumerated values, that’s a little better now in UI4

Please dont take this the wrong way, but this seems like a bit of an anti-pattern and inconsistent with other devices. Just because a UI may be dumb, doesnt mean we should drop everything to that level. Since the mainstream APIs still arent supporting this device type yet, maybe now is the prime time to get things sorted out.

The Security Sensor device only has the Armed property, and most other devices would be the same. Dimmable light switches for example have a binary status, and then a levelstatus which is within a range - I dont see why the same concept shouldn’t apply to alarm systems. You may have a point around how the UIs handle enumerated values - I dont know enough about that yet, but a binary status and free-form detail should be sufficient for the “dumb” UIs, while providing enough power and flexibility for those that want to get down and dirty with actions to apply.

Agreed, but be aware that UI2 actually looks at this interface in order to provide it’s rudimentary UI. Since they’ve fixed that in UI4, by making it more flexible, we’re open to change things there at free-will, but will need to tweak the name/version somewhat to represent “new” and “old” versions.

eg. :2 instead of :1

Why don’t you take a crack at putting together a package of modified “common” API’s and Service vars, including potentially some of the Scene-based items (although less important for commonality here), and float it here.

It seems like you, me and @futzle are the only ones that really need to agree at this time (it’s been 2.5 mo since Javier has been on the Forums)

More than happy to make changes if we can agree to some common API’s, Services and potentially Scene/Events. I know that MCV wants that, and I’m sure the Control Point lads would be supportive of extending it to the iPhone and Android interfaces if we can do it.

The wish list I think includes additions for:

a) Listing the last User who “did something” on a given Partition (Arm/Disarm etc) - where “User” is some arbitrary string for display purposes (@futzle has this)
b) Listing the Last Zone, or Zone-list, in Trouble (since the trouble may have passed). We need common representation (comma-list, etc) ZoneId or Zone-Label, etc in order for Control Points to be able to render it.
c) Merging the Disarm/Arm/StayArm states as a single, multi-valued, Service Variable

Feel free to add here if we think there are extra API’s or Service variables that can be made “common” across Panel implementations. We may also want a convention on how to handle/name Device-specific extensions (if any)

BTW: If you’re basing your code upon the DSC starter plugin on code.mios.com, you’ll want to modify it so it stores the “Password” (PIN Code) outside of a Variable (in a File, perhaps). These “values” get shunted up to [tt]cp.mios.com[/tt] servers, either through a backup, or your daily [tt]LuaUPnP.log[/tt], and you really don’t want your Alarm code PINs being moved around like that.

Can we standardize the meaning of “Breached”?

There are two values that the Caddx panel provides and both are useful:

One is “The siren is sounding right now.”

Two is “This partition has recovered but the siren wassounding.”

I reckon we need both, but which one is the current “Breached”?

@futzle,
To get the discussion moving, I’ve taken some of the comments here and prototyped/attached [tt]S_AlarmPartition2.xml[/tt]… this time with a few more comments indicating “intent” for the vars and actions.

It’s far from complete, but tries to handle some of the issues you’d previously raised (along with the Breach one you just listed).

There are some things that I still don’t know how to be represent, including:
a) Whether “getter” methods should be provided for the State vars - UPnP Conventions, seems all over the map.
b) How to handle returning a “list” of things, like (b) for Zones “out of whack” due to a Breach.
c) Should we be complete and try to expose Zones and the like, even though (in MiOS) we have another way to get them?
d) How to represent “dates/datetime/Timezone” events in UPnP - what DT was that?
e) Should we bother with the transitionary states that I’ve represented (including Arming, Disarming)
f) How we handle “device-specific” extensions, including any naming conventions required.

Anyhow, there’s enough detail in the Service descriptor file to trigger commentary.

No idea. What additional value would they give us?

b) How to handle returning a "list" of things, like (b) for Zones "out of whack" due to a Breach. c) Should we be complete and try to expose Zones and the like, even though (in MiOS) we have another way to get them?
That's a big can of worms. Are zones numbered, or do they have names? Are they unique within a panel, or can each partition have a Zone 1, Zone 2, and so on? Do we store alarm-panel numbers or device numbers? I'm tempted to avoid the problem and make the implementation put a service variable straight onto the zone device instead.
d) How to represent "dates/datetime/Timezone" events in UPnP - what DT was that?
It looks like UPnP likes to use ISO8601 DateTimes ("20110113T195921+1100"). Easy enough to parse in Luup, and can handle degraded precision, if for instance the alarm panel doesn't know the seconds or time zone, it's still unambiguous. We could choose worse than ISO8601.
e) Should we bother with the transitionary states that I've represented (including [i]Arming[/i], [i]Disarming[/i])
Definitely. People will want to have scenes that operate during entry delay. That's good enough reason to include them IMO.

But I’m not crazy about them being states in their own right. Imagine an armed partition when a zone gets triggered. The states will go: Armed + NoBreach -> Disarming + NoBreach -> Armed + CurrentlyBreached. Writing scenes to handle these states will be Tricky, especially since we don’t have AND logic in scene triggering.

Instead I recommend that another state variable EntryExit be created, with values None, EntryDelay and ExitDelay. That gives users the ability to make scenes for almost any condition without having to combine variables.

Definitions:
None: The partition is in a static state (disarmed or armed), or no better information is available.
EntryDelay: The partition is Armed or StayArmed, and the user has a finite time to Disarm the system or the partition will enter a Breach state. This is normally triggered by a zone in the partition being Tripped. The Armed/StayArmed State does not change until it is actually Disarmed.
ExitDelay: The partition has just been Armed or StayArmed. A typically use is while user is leaving the secure area: the user may still Trip Zones during Exit Delay without causing a Breach. The Armed/StayArmed State remains Disarmed until the Exit Delay ends.

There are no guarantees that an EntryDelay will be followed by a Disarm (there may be an imminent breach), or that a Breach will be preceded by an EntryDelay (a zone can be instant-breach), or that an ExitDelay will be followed by an Arm/StayArm (the partition may be insecure at the end of the exit period and cancel the arming). Panels need only implement EntryExit=None, for instance, if they have no concept of Entry/Exit delay or do not expose it to their automation interface.

f) How we handle "device-specific" extensions, including any naming conventions required.

Like the Virtual Inputs of the Paradox panel, for instance? Caddx has nothing like that. I dunno. Is it possible to put two services on the partition device: one the generic Partition service we’re talking about here, and one for the panel-specific stuff?

With respect to the :2 XML file, I’ve got some comments:

CancelArm
Looks like the Caddx interface can report when this has happened, but it doesn't give a way to trigger the action. I'll have to have this action fail as "not implemented".
Do we need a way of indicating if these "capabilities" exist or not for Service Actions that may have no Alarm-specific implementation?
That's probably something for the UPnP-interface users (e.g., iVera and SQ Remote) to tell us if they'd use it. On the Vera itself a Panel's implementation already knows the answer, and users can get "action failed" visual feedback on the web interface.

No idea. What additional value would they give us?[/quote]
It was more of a “purist” thing, as to whether we should define the API to be like one from UPnP itself, rather than something MiOS specific.

I really don’t mind either way, and am happy to just go with the State var stuff, since I’m not sure how MiOS implements the return state for a getter anyhow. If I work it out, I’ll add them to the S_xxx.xml and document how to impl.

b) How to handle returning a "list" of things, like (b) for Zones "out of whack" due to a Breach. c) Should we be complete and try to expose Zones and the like, even though (in MiOS) we have another way to get them?
That's a big can of worms. Are zones numbered, or do they have names? Are they unique within a panel, or can each partition have a Zone 1, Zone 2, and so on? Do we store alarm-panel numbers or device numbers? I'm tempted to avoid the problem and make the implementation put a service variable straight onto the zone device instead.
Yup, exactly. Happy to leave it out for the moment, but figure the item will need to be tackled at some point. ... and no, I wasn't intending to ever use Vera Device #'s, but more of a "Vendor specific handle" to each Zone.

Will leave it out of scope for now, can revisit when we do Interface gen 3, once we have some more experience under our [collective] belt. :slight_smile:

d) How to represent "dates/datetime/Timezone" events in UPnP - what DT was that?
It looks like UPnP likes to use ISO8601 DateTimes ("20110113T195921+1100"). Easy enough to parse in Luup, and can handle degraded precision, if for instance the alarm panel doesn't know the seconds or time zone, it's still unambiguous. We could choose worse than ISO8601.
Ok, so looks like they're represented as "dateTime" in the datatype. I'll shoot for dateTime, instead of dateTime.tz, and see whether MiOS even supports this DT.
e) Should we bother with the transitionary states that I've represented (including [i]Arming[/i], [i]Disarming[/i])
Definitely. People will want to have scenes that operate during entry delay. That's good enough reason to include them IMO.

But I’m not crazy about them being states in their own right. Imagine an armed partition when a zone gets triggered. The states will go: Armed + NoBreach -> Disarming + NoBreach -> Armed + CurrentlyBreached. Writing scenes to handle these states will be Tricky, especially since we don’t have AND logic in scene triggering.


Yeah, that’s not the intent. The Arming status of the Panel isn’t expected to change when a Breach occurs. Typically “Arming” is something that a user does to set the system into a mode for detection.

Breaching occurs when a detection event occurs, and it’s in one of the Arming states. The Partition should stay in the Armed state during this period as, technically, it’s still armed but something else is going on.

I would expect to see a state transition series more like:

Armed + NoBreach
Armed + CurrentlyBreached
Armed + PriorBreach
Disarming + (PriorBreach | NoBreach)
Disarmed + (PriorBreach | NoBreach)
Instead I recommend that another state variable EntryExit be created, with values None, EntryDelay and ExitDelay. That gives users the ability to make scenes for almost any condition without having to combine variables.
Given the above clarification of intent, do you still see need for this additional state var? I'd like to avoid it as I believe the Status var is the "logical" representation of the state(s) in a State Transition diagram, including actions that would push it from the "fixed" states (Disarmed) into the transitional states (Arming) and into another permanent state (Armed)

So they’re really independent “states”, except perhaps that one might never see “Disarmed + CurrentlyBreached” but that’s more for the Panel implementor to worry about. :slight_smile:

Things like [tt]RequestArmCancel()[/tt] are intended to work in that transition diagram when it’s in these “transitionary” states.

f) How we handle "device-specific" extensions, including any naming conventions required.

Like the Virtual Inputs of the Paradox panel, for instance? Caddx has nothing like that. I dunno. Is it possible to put two services on the partition device: one the generic Partition service we’re talking about here, and one for the panel-specific stuff?


Right, that was my original thought. Have each Panel define a Panel-specific Service, with a panel-vendor like URN string. Then the Panel-specific methods (etc) can go in there.

More than happy to put the VI stuff in there also, have seen at least one other Panel that had the ability to do that, so figured it a “blurry” case, perhaps one looking for standardization. The “garage door” case that was cited in your other thread would fit this case… if it’s possible to push that data into the Caddx.

CancelArm
Looks like the Caddx interface can report when this has happened, but it doesn't give a way to trigger the action. I'll have to have this action fail as "not implemented".
Yeap, not clear on the best way to indicate [to UPnP] that it's not implemented. I know the SQRemote lads use the [tt]lu_actions[/tt] calls to determine what methods exist, so presumably they won't present that part of the UI.

Since this is MiOS specific, I’ve not seen how purist UPnP implementers are expected to indicate that a Method hasn’t got an implementation.

ie. implement it, but raise an Exception/Error of some sort, or just not implement it.

So this is the “Entry Delay” state by your definition. In that case, we’ve been each assuming our own definition of what “Breach” means. It isn’t a word that the Caddx panel uses, so I’ve been mapping it onto “is in an alarm state”, whereas I think you have it mean “is in an insecure state”.

If that’s the case, we still don’t have enough states, because Caddx can represent:
Armed + secure
Armed + in entry delay
Armed + siren blaring in alarm state
Armed + siren silent + remembers alarm that has happened since arming
Armed + in exit delay

So they're really independent "states", except perhaps that one might never see "Disarmed + CurrentlyBreached" but that's more for the Panel implementor to worry about. :-)

I guess I don’t agree about what the states in the transition diagram are. Perhaps that’s because our views are coloured by the respective panels that we use. I recommend that we both go away and draw up how we imagine the transition diagram for the entire system looks, using the system’s native terminology, showing armed states, alarm states, and what transitions lead from one to the other, and come back and compare pictures.

@futzle,
Some starter diagrams, using the states of my Panel and the terms it uses also.

Arming states are distinctly separate from Alarm states, so there’s two diagrams. Note that the Alarm states, in their current form, can only occur if my panel is Armed. This isn’t 100% accurate due to the ability to trigger the Police/Fire/Emergency Alarms without ever entering the Armed state, so still have to model those in.

Diagrams presented just to give you a sense for it.

And here’s my state diagram for the Caddx panel. I haven’t looked at yours yet, so there’s no way we’ve polluted each other. :slight_smile:

Any updates on this? I just got repo access to the DSC plugin and I would like to standardize it soon. The partition states are pretty much identical to the Paradox panel. I was thinking about the following variables:

boolean Ready
boolean Armed
boolean Trouble

– The above could be used to simulate status LEDs in the UI

boolean InAlarm
enum ArmedDetail: Away, Stay, Instant, vendor specific values
string StatusMessage: LCD message, transitional states (exit, entry delay) message, vendor specific messages

Thanks

[quote=“digitalperk, post:19, topic:166000”]Any updates on this? I just got repo access to the DSC plugin and I would like to standardize it soon. The partition states are pretty much identical to the Paradox panel. I was thinking about the following variables:

boolean Ready
boolean Armed
boolean Trouble

– The above could be used to simulate status LEDs in the UI

boolean InAlarm
enum ArmedDetail: Away, Stay, Instant, vendor specific values
string StatusMessage: LCD message, transitional states (exit, entry delay) message, vendor specific messages

Thanks[/quote]
Not yet, been a little tied up.

@strangely sent me a DSC he was building, and I took the time yesterday to rebuild the DSC Plugin code. It’s about 70% re-written at the moment, and when I’m complete it will be aligned with the “version 1” common API that both @futzle and I use (for GE CADDX and Paradox resp)

It was a good exercise, since the code for that Plugin is a lot cleaner, even after the partial that I’ve done so far. It also shows me some interesting differences (like some stuff in the DSC that only occurs at the Panel Level, whereas the GE and Paradox have them occurring at the Partition level)

If you’d like to take a stab, it would be handy if you did a model diagram for how you see the DSC functioning, in terms of it’s states, and transitions. I have a mental model, but want to finish the first-round re-write before I go further, having a new set of eyes draw the picture would be handy as a “3rd” data point to this discussion.

Then we can move onto proposals to align, based upon the diagrams and a [hopefully] common understanding of each others systems.

Anyhow, I reworked the DSC code yesterday, to address a list of issues I saw that were going to make it hard to align, and/or debug/use, such as:

[ul][li]Storing the PINCode of the Panel (which would then get uploaded to MCV Servers, a potential security problem)[/li]
[li]No “Auto” configuration of anything, users were left unclear on how to get an initial config running.[/li]
[li]No native handling of IP Attached Panels (I develop using Wifi-attached, others might use WIZnet etc)[/li]
[li]Move to Table/Function driven for most common events (Panel, Zone, Partition) to avoid all the custom logic[/li]
[li]Lack of Alignment with the standards set by the existing AlarmPartition1 ServiceId (Paradox and GE CADDX)[/li]
[li]No separation of the DSC-specific bits from the common/core Alarm Panel bits (Paradox and GE CADDX)[/li]
[li]Missing methods that were being called, but weren’t present (leading to log errors)[/li]
[li]Errors in the logs due to improper parsing/handling of certain common situations in the Panel messages.[/li]
[li]No Standardization of the logging/diagnostics, making the logs hard to locate/diagnose[/li][/ul]

PS: Both @strangely and I also have access to the DSC Plugin Trac, so let me know what you’re intending to change so it can be incorporated. For my checkin, there will be no upgrade path, since the “v1” alignment changes are substantial. I will be checking this in as a branch (of sorts) so-as not to disrupt the original code that Javier wrote (but it will be in the same Trac)