zz Alarm Command Class

OUTDATED - This page needs updating

Introduction

The Alarm CommandClass is rather complex implementation. This page is intended as a guide for Developers on how to interact with devices that Support the Alarm CommandClass. This document covers the changes that were introduced in Version 1.6 of OZW.

Background

Version 1 of the Alarm CommandClass was fairly loosely defined by protocol, and allowed Device Manufacturers the ability to define how "Alarms" could be communicated to other devices. This means that apart from the actual protocol there is no definition of different types of Alarms that could occur in a Z-Wave Network.

The problem with this approach is interoperability. As each manufacturer could define different types of Alarms etc, it means there was no way for OZW to have a well defined API that was common among different devices. As a result, UI's and Application Logic could be combersome.

With Version 2 of the Alarm CommandClass, Sigma have predefined a set of Alarm Types and Alarm Events. This pre-defined list covers the majority of types of Alarms that can occur, but as they promise backwards compatibility, manufacturers can still specify their "custom" alarm types in addition to using the predefined Alarms.

#Implementation Details The following sections will cover the implementation details of the different versions of the Alarm CC.

Version 1

As mention, Version 1 of the Alarm CC allowed manufacturers to specify the Alarm Type and Alarm Event, and no consistency was present between Vendors

For Devices that support Version 1 of the CommandClass, OZW has implemented as follows:

• 2 ValueID's are exposed from the Alarm CC

Alarm Type - Index 0 - This Value is a single byte, and its value should be specified in the Device Manuals or Technical Documents Alarm Level - Index 1 - This Value is either a Single Byte, or a List. What a Single Byte respresents is upto the Manufacturer and should be specified in the device manual. Some Devices, this would be represented as a ValueList, and all possible values are specified in the devices configuration file.

In order to create a configuration file for Version 1 files, as example as per below us provided:

<CommandClass id="113" name="COMMAND_CLASS_ALARM">
	<Value type="byte" genre="user" instance="1" index="0" label="Alarm Type" units="" read_only="true" write_only="false" verify_changes="false" min="0" max="255" value="12">
		<Help>Grouping 1, afterward, LED will light up for 1 sec to remind user when HSM02 is triggered due to open or close incidents.</Help>
	</Value>
	<Value type="list" genre="user" instance="1" index="1" label="Alarm Report" read_only="true" write_only="false" verify_changes="false" vindex="0" value="0" size="1">
		<Help>
			No alarm : There is no alarm to report. 
			Power applied : Once the power has been applied, Alarm Report Command will be sent to
			Nodes in Grouping 1 to confirm the power applied status for HSM02. 
			Tamper event : Grouping 1, afterward, LED will light up for 1 sec to remind user when HSM02 is
			triggered due to open or close incidents. 
			Low battery : When HSM02 automatically wakes up, it will check the battery usage. When
			low battery is detected, Alarm Report Command will be sent to Nodes in
			Grouping 1, afterward, LED will light up for 1 sec to remind user when HSM02 is
			triggered due to open or close incidents.
		</Help>
		<Item label="No alarm" value="0" />
		<Item label="Power applied" value="2" />
		<Item label="Tamper event" value="17" />
		<Item label="Low battery" value="255" />
	</Value>
</CommandClass>

The Line <Value type="byte" genre="user" instance="1" index="0" label="Alarm Type" units="" read_only="true" write_only="false" verify_changes="false" min="0" max="255" value="12"> allows you to specify some help text with the Associated Alarm Type Entry. The only thing you should modify is the actual Help Text below this entry.

The Lines below with <Value type="list" genre="user" instance="1" index="1" label="Alarm Report" read_only="true" write_only="false" verify_changes="false" vindex="0" value="0" size="1"> allow you to customize the Help Text and the Actual List that the user will see. You should Modify the List Items as per the Device Manual.

These Two ValueID's are unique and will be only present on Version 1 Devices

Version 2

With the introduction of Version 2, there are now standard Alarm Types and Alarm Events, ranging from things such as Smoke Detectors through to Buglar and Even Alarm Clocks! With each type of Alarm, there is also a Alarm Event. (eg, with the Buglar Type, there could be a Intrusion, or a Tamper Event). Additionally, some Events can optionally provide some additional details, such as Location, or UserID's etc.

For Devices that Support Version 2 or higher, we do not expose any Version 1 ValueID's anymore, and only expose the following ValueID's: SourceNodeId - Index 2 - This is the Source Node that generated the Alarm.Exposed as a Byte Value Then Depending upon the Types of Alarms the Device Supports, a range of ValueID's will be exposed with their index corrosponding the the Alarm Type. The Current list (as of Development of 1.6) is:

enum { Alarm_General = 0, Alarm_Smoke, Alarm_CarbonMonoxide, Alarm_CarbonDioxide, Alarm_Heat, Alarm_Flood, Alarm_Access_Control, Alarm_Burglar, Alarm_Power_Management, Alarm_System, Alarm_Emergency, Alarm_Clock, Alarm_Appliance, Alarm_HomeHealth, Alarm_Count }; (you should check the Source of the Alarm CommandClass for updated list as this might change).

Each ValueID is a List, and will be exposed with the index of the above Enum + 3. (so ValueID Index 9 for the Alarm_Access_Control type)

The List will then present all possible Events for a given Alarm type, so in the example of the Alarm_Access_Control you will have a list of Events such as Manual_Lock, Manual_Unlock, KeyPad Lock etc. In addition, all Events have a "Not Active" Event type, which means that the Alarm is not currently active.

Finally, some Event types expose additional information, such as Location, or UserCodes. These ValueID's will be present at Index 200 and will be created and deleted as different Events occur (so you can't expect them to be present all the time).

A example of a Event that has additional information is with the Alarm_Access_Control Type and Alarm_Access_Control_KeyPad_Lock Event exposes a Additional ValueByte containing the UserCode Position that was entered on the device.

Other Events can expose information sent from the Device, such as Location. While support for these "String" types has been implemented, it has not been tested, so if any errors occur when recieving such events from devices, please report it to the developers with a LogFile attached.