3.2.8. Association Group Information (AGI) Command Class, version 1¶

The Association Group Information (AGI) Command Class allows a node to advertise the capabilities of each association group supported by a given application resource.

\requirement{CC:0059.01.00.12.001}{0}

Controllers and installer tools SHOULD use AGI information to support controller-assisted button-to-button association and GUI-based drag-and-drop association in a plug-and-play fashion.

Centralized gateway-based deployments may create a single association from the lifeline association group to a central management application.

3.2.8.1. Compatibility considerations¶

\requirement{CC:0059.01.00.21.001}{0}

A node supporting the AGI Command Class MUST support the Association Command Class.

3.2.8.1.1. Multi Channel considerations¶

The Association Group Information (AGI) Command Class also applies to Multi Channel devices.

\requirement{CC:0059.01.00.21.002}{4}

If a node implements Multi Channel End Points and supports the AGI Command Class, each individual End Point MUST support the AGI Command Class.

3.2.8.2. Association Principles¶

A light control transmitter may have one or more keys. A key is mapped to one or more association groups.

Figure 3.1 Light Control Transmitter (example)¶

A light control transmitter key can be configured to control a lamp by adding the NodeID of the lamp to an association group that represents the key.

3.2.8.3. The Association Group Information¶

\requirement{CC:0059.01.00.12.002}{4}

A node may implement one or more association groups. If the device implements association groups, the device SHOULD provide an Association Group Information (AGI) table as described in Table 3.25.

Table 3.25 Layout of One Line of the Association Group Information Table¶
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes

An AGI table entry carries a number of fields. The information is typically static and can be defined at compile time. Thus, the AGI table does not need to occupy any RAM or non-volatile storage.

3.2.8.3.1. Group identifier¶

The Group identifier indicates which association group the actual table entry relates to. As association groups are always numbered in a sequence starting from 1, an actual implementation does not have to store the group identifier in its memory. The number of association groups may be requested via the Association Groupings Get or Multi Channel Association Groupings Get commands.

\requirement{CC:0059.01.00.11.001}{0} \requirement{CC:0059.01.00.11.002}{8} \requirement{CC:0059.01.00.13.001}{12}

Association group 1 is reserved for the Z-Wave Plus Lifeline association group. Group 1 MUST NOT be assigned to any other use than the Lifeline group. The actual Device Type specifies a mandatory list of commands which the device MUST send to all targets associated to the Lifeline group. A manufacturer MAY add additional commands to the Lifeline group. Refer to [35] and Device Type v2 Specification.

\requirement{CC:0059.01.00.11.003}{0} \requirement{CC:0059.01.00.12.003}{4}

The Lifeline group MUST be advertised for the Root Device of a Multi Channel device. A Multi Channel End Point SHOULD advertise commands for association group 1 which End Points can send via the Root Device Lifeline group if a Multi Channel Association is created from the Root Device Lifeline group.

3.2.8.3.2. Profile¶

\requirement{CC:0059.01.00.13.002}{0}

A device MAY implement one or several AGI profiles. The profile defines the scope of events which triggers the transmission of commands to the actual association group. As an example a temperature sensor may issue different Basic Set Command parameters when the temperature exceeds a threshold and when the temperature drops below a threshold. The actual behavior is application dependent and out of scope of the AGI Command Class.

The profile identifiers are referenced in Table 3.36 - AGI Profiles. Profiles are divided into categories in the following sections.

3.2.8.3.2.1. General profiles¶

\requirement{CC:0059.01.00.11.004}{4}

The “General” category comprises the “Not Applicable” and “Lifeline” profiles. The “Not Applicable” profile identifier MUST be advertised if the actual association group does not match any of the defined profiles.

\requirement{CC:0059.01.00.11.005}{0}

The “Lifeline” profile identifier MUST be advertised for association group 1 of the Root Device.

3.2.8.3.2.2. Control profiles¶

“Control” profiles are intended for association groups of which commands are triggered by a user control mechanism, such as keys or buttons. As an example, a light control transmitter may comprise two control keys that can each control a group of lamps.

A control key may control up and down dimming as well as on/off state. Thus, a control key may send more than one command with one specific parameter. A control key may be implemented as a physical key, a group of icons, touch screen gestures or other means. The actual implementation is out of scope of this command class.

\requirement{CC:0059.01.00.13.003}{0}

In case of multiple logical functions in a device, the device MAY implement one Multi Channel End Point for each logical function; e.g. each push button is implemented as a separate End Point. Table 3.26 gives an example of a Multi Channel a battery-powered two-button light control device.

Table 3.26 Example: AGI Tables for Two-Button Light Control Transmitter¶
Root Device:
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	General: Lifeline	Central Scene Notification Notification Report Battery Report Device Reset Locally Notification	Lifeline
2	Control: Key1	Basic Set	On/Off control (Button 1)
3	Control: Key1	Multilevel Switch Set	Dimmer control (Button 1)
4	Control: Key2	Basic Set	On/Off control (Button 2)
5	Control: Key2	Multilevel Switch Set	Dimmer control (Button 2)
End Point 1:
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	General: Lifeline	-	Lifeline
2	Control: Key1	Basic Set	On/Off control (Button 1)
3	Control: Key1	Multilevel Switch Set	Dimmer control (Button 1)
End Point 2:
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	General: Lifeline	-	Lifeline
2	Control: Key2	Basic Set	On/Off control (Button 1)
3	Control: Key2	Multilevel Switch Set	Dimmer control (Button 1)

The Profile identifiers Control:Key 1 and Control:Key 2 allows an installer tool to determine which Multi Channel End Point and which association group to use in order to configure buttons to control a light dimmer. The Group Name allows a human user to make a qualified decision even if the installer tool is not, e.g. because it is running an older version not updated with newer profile identifiers.

End Points 1 and 2 in the above example do not support any Command Class that must be sent via the Z-Wave Plus Lifeline. Therefore End Points 1 and 2 advertise an empty Command Class list for the Lifeline association group.

\requirement{CC:0059.01.00.12.004}{4}

The Root Device in the above example advertises the Basic Set Command in association group 2. This is a feature of End Point 1. A controlling node SHOULD NOT create associations from other Root Device association groups than the Lifeline group if it supports the Multi Channel Command Class. The purpose of the Root Device Association Groups (with the exception of the Lifeline group) is only to provide backwards compatibility for legacy devices without support for the Multi Channel Command Class.

3.2.8.3.2.3. Sensor profiles¶

“Sensor” profiles are intended for association groups of which commands are triggered by sensor readings. As an example, a sensor product could comprise two temperature sensors.

Sensor profile identifiers are constructed by prepending the Multilevel Sensor Command Class identifier (referred to with AGI_PROFILE_SENSOR) to a multilevel sensor type defined in the Multilevel Sensor Command Class. The values in Table 3.36 only serve as examples to illustrate the construction of AGI Sensor Profile Identifiers. For the full list of available sensor types, refer to the “Multilevel Sensor Report Command”.

\requirement{CC:0059.01.00.12.005}{0}

In case of multiple logical functions in a device, the device SHOULD implement one Multi Channel End Point for each logical function; e.g. each sensor instance is implemented as a separate End Point. Table 3.27 gives an example of a Multi Channel battery-powered sensor device with two multilevel sensor functions:

Table 3.27 Example: AGI Tables for Two-Function Sensor¶
Root Device:
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	General: Lifeline	Multilevel Sensor Report Notification Report Battery Report Device Reset Locally Notification	Lifeline
2	Sensor: Temperature	Basic Set	On/Off control (Indoor temperature)
3	Sensor: Temperature	Basic Set	On/Off control (Outdoor temperature)
End Point 1
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	Sensor: Temperature	Multilevel Sensor Report	Indoor temperature via Lifeline
2	Sensor: Temperature	Basic Set	On/Off control (Indoor temperature)
End Point 2
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	Sensor: Temperature	Multilevel Sensor Report	Outdoor temperature via Lifeline
2	Sensor: Temperature	Basic Set	On/Off control (Outdoor temperature)

The Profile identifier is Sensor:Temperature for both End Points but the Group Name allows a user to determine which End Point and which association group to use in order to configure the indoor temperature sensor to control a heating element.

The Root Device in the above example advertises the Multilevel Sensor Report command in the Lifeline group. Residing in a Multi Channel device, the Root Device does not actually implement any application functionality. The Multilevel Sensor Report Command is a feature of the End Points which is advertised for backwards compatibility with legacy devices not supporting the Multi Channel Command Class.

Likewise, the Root device advertises the Basic Set Command in association groups 2 and 3. This is also a feature of the End Points. Refer to the Multi Channel Command Class for details on backwards compatibility.

End Point 1 in the above example advertises the Multilevel Sensor Report Command in association group 1. By advertising that zero NodeIDs are supported for association group 1, End Point 1 indicates that this command is sent via the Root Device Lifeline group if a Multi Channel association is created for the Root Device Lifeline group. The same principle applies to End Point 2.

3.2.8.3.2.4. Notification profiles¶

“Notification” profiles are intended for association groups of which commands are triggered by detected events or state changes. As an example, a detector product could comprise one smoke sensor and one CO2 detector.

Notification profile identifiers are constructed by prepending the Notification Command Class identifier (referred to with AGI_PROFILE_NOTIFICATION) to a notification type defined in the Notification Command Class. The values below only serve as an example to illustrate the construction of AGI Notification Profile identifiers. For the full list of available notification types, refer to the Notification Command Class (Section 2).

\requirement{CC:0059.01.00.12.006}{0}

In case of multiple logical functions in a device, the device SHOULD implement one Multi Channel End Point for each logical function.

The following example outlines how a standalone smoke alarm is represented by an AGI table:

Table 3.28 Example: AGI Table for One-Function Alarm Device¶
Root Device:
Group identifier	Profile 2 bytes	Command Class & Command (list) N bytes	Group Name (UTF-8) M bytes
1	General: Lifeline	Notification Report Battery Report Device Reset Locally Notification	Lifeline
2	Notification	Basic Set	On/Off control (Smoke)

The Profile identifier Notification SmokeAlarm indicates to an installer that the Basic Set Command of association group 2 is issued in response to smoke alarm events.

3.2.8.3.3. Command Class and Command¶

\requirement{CC:0059.01.00.13.004}{4}

This field contains the command class and the command that is sent to targets associated with this association group if an event occurs. This field MAY advertise a list of commands and MAY contain a combination of extended and normal command classes. Refer to Section 3.2.8.9.

The command list is used by a controlling application to discover what functionality the node provides via a given association group. It also allows the controlling node to ensure that the associated node understands the received commands.

\requirement{CC:0059.01.00.13.005}{0}

A node MAY list only one command if the actual association group sends different commands which actually relate to the same overall functionality and belong to the same Command Class and Commands Class version (e.g. Multilevel Switch Set / Multilevel Switch Start Level Change / Multilevel Stop Level Change)

\requirement{CC:0059.01.00.12.007}{4}

In case Multi Channel End Points are implemented, the Lifeline association group (group 1) of End Points SHOULD be used to advertise commands that will be sent via the Root Device Lifeline group if a Multi Channel association is created from the Root Device Lifeline group.

3.2.8.3.4. Association group name¶

This field contains a name reflecting the purpose of the group, e.g. “On/Off control (Smoke)”.

\requirement{CC:0059.01.00.11.006}{0}

The Root Device Lifeline group MUST be named “Lifeline”.

\requirement{CC:0059.01.00.11.007}{0}

Group names MUST be encoded using UTF-8. The available capacity for characters depends on the actual characters encoded with UTF-8. Plain ASCII characters only occupy one byte while special characters may need two or more bytes for representation.

3.2.8.4. Association Group Name Get¶

This command is used to query the name of an association group.

\requirement{CC:0059.01.01.11.001}{0}

The Association Group Name Report Command MUST be returned in response to this command.

\requirement{CC:0059.01.01.11.002}{0}

This command MUST NOT be issued via multicast addressing.

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 3.29 Association Group Name Get¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_NAME_GET (0x01)
Grouping Identifier

Grouping Identifier (1 byte)

This field is used to specify the requested association group identifier.

\requirement{CC:0059.01.01.12.001}{0}

A node receiving this command for an unsupported Grouping Identifier SHOULD return information relating to Grouping Identifier 1.

3.2.8.5. Association Group Name Report¶

This command is used to advertise the assigned name of an association group.

Table 3.30 Association Group Name Report¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_NAME_REPORT (0x02)
Grouping Identifier
Name Length
Name 1
…
Name N

Grouping Identifier (1 byte)

This field is used to advertise the actual association group identifier.

Name Length (1 byte)

\requirement{CC:0059.01.02.11.001}{0}

This field indicates the length in bytes of the Name field. The value MUST be in the range 0..42.

Name (N bytes)

This field is used to indicate the assigned name for the actual Group Identifier.

\requirement{CC:0059.01.02.11.002}{0}

The length of this field in bytes MUST comply with the advertised value in the Name Length field.

\requirement{CC:0059.01.02.11.003}{0}

The string MUST NOT contain any appended termination characters.

\requirement{CC:0059.01.02.11.004}{0}

The characters MUST be encoded in UTF-8 format.

3.2.8.6. Association Group Info Get¶

This command is used to request the properties of one or more association group.

\requirement{CC:0059.01.03.11.001}{0}

The Association Group Info Report MUST be returned in response to this command.

\requirement{CC:0059.01.03.11.002}{0}

This command MUST NOT be issued via multicast addressing.

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 3.31 Association Group Info Get¶
7	6	5
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_INFO_GET (0x03)
Refresh cache	List Mode	Reserved
Grouping Identifier

List Mode (1 bit)

This field is used to request the properties of the supported association groups of a node.

\requirement{CC:0059.01.03.11.003}{0} \requirement{CC:0059.01.03.13.001}{4}

If List Mode is set to 1, a receiving node MUST ignore the Grouping Identifier field and return the properties of all its supported associations groups. The receiving node MAY return the response in several Reports, (e.g. due to memory constraints or a high number of association groups).

\requirement{CC:0059.01.03.11.004}{0}

If List Mode is set to 0, a receiving node MUST advertise the properties of the association group identified by the Grouping Identifier.

\requirement{CC:0059.01.03.11.005}{0}

The Association Group Info Report returned in response to this command MUST advertise the same List Mode value as specified by this field.

Refresh Cache (1 bit)

\requirement{CC:0059.01.03.11.006}{0}

If AGI information is transferred via a gateway, the gateway MUST cache information for all nodes; also listening nodes.

The AGI Get command flag “Refresh Cache” is used by a management application to instruct a gateway to update its cache on the first chance given. In case of a sleeping device, this may require a user operation to wake up the device. In case of a Wake Up device, the gateway may wait for the next Wake Up Notification from the actual device.

\requirement{CC:0059.01.03.11.007}{0}

The “Refresh Cache” value 0 MUST specify that the gateway is to return its cached information.

\requirement{CC:0059.01.03.11.008}{0}

The “Refresh Cache” value 1 MUST specify that the gateway is to return its cached information and update its cache on the first chance given.

\requirement{CC:0059.01.03.12.001}{0}

The “Refresh Cache” SHOULD be set to 0 by a sending node.

\requirement{CC:0059.01.03.13.002}{4}

A receiving node may have re-configurable AGI properties, e.g. if it is a configurable multi-purpose remote control. If the “Dynamic Info” flag of the AGI Report command is set to 1, a sending node MAY set the “Refresh Cache” flag in the AGI Get command to force the gateway to update its cache, e.g. after the sending node has re-configured the AGI properties of the receiving node.

Reserved

\requirement{CC:0059.01.03.11.009}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Grouping Identifier (1 byte)

\requirement{CC:0059.01.03.11.00A}{0}

This field is used to specify the requested association group identifier. This value MUST be ignored if the List Mode field is set to 1.

\requirement{CC:0059.01.03.12.002}{0}

A node receiving this command for an unsupported Grouping Identifier SHOULD return information relating to Grouping Identifier 1.

3.2.8.7. Association Group Info Report¶

This command is used to advertise the properties of one or more association groups.

Table 3.32 Association Group Info Report¶
7	6	5
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_INFO_REPORT (0x04)
List mode	Dynamic Info	Group Count
Grouping Identifier
Mode = 0
Profile MSB
Profile LSB
Reserved = 0
Event Code MSB = 0
Event Code LSB = 0
…
Grouping Identifier
Mode = 0
Profile MSB
Profile LSB
Reserved = 0
Event Code MSB = 0
Event Code LSB = 0

List Mode (1 bit)

\requirement{CC:0059.01.04.11.001}{0}

The List Mode field MUST advertise the same value as specified in the Association Group Info Get command which caused this command to be returned.

\requirement{CC:0059.01.04.13.001}{0}

If List Mode is 1, a sending node is advertising the properties of all association groups. The sending node MAY return several Reports.

\requirement{CC:0059.01.04.11.002}{0}

If List Mode is 0 a sending node MUST advertise the properties of one association group.

Dynamic Info (1 bit)

\requirement{CC:0059.01.04.13.002}{0} \requirement{CC:0059.01.04.11.003}{4}

If the Dynamic Info field is set to 1, the information MAY change and a controlling node SHOULD perform periodic cache refresh for this node. Nodes MUST set this bit if they are able to change the Association Group Information on the fly.

\requirement{CC:0059.01.04.11.004}{0}

If this field is set to 0, a controlling node MUST NOT request this information more than one time.

Group Count (6 bits)

\requirement{CC:0059.01.04.11.005}{0}

This field indicates the number of association groups advertised in the command. The Grouping Identifier, Mode, Profile, Reserved and Event Code fields MUST be repeated for each association group.

\requirement{CC:0059.01.04.11.006}{0}

If List Mode is set to 0, the Group Count field MUST be set to 1.

If List Mode is set to 1, the Group Count field MUST advertise the number of association group property blocks following this field.

A node receiving this report may determine the total number of association groups via the Association Supported Groupings Get or Multi Channel Association Supported Groupings Get commands.

Grouping Identifier (1 byte)

\requirement{CC:0059.01.04.11.007}{0}

This field MUST advertise the association group identifier of the actual association group property block.

Mode (1 byte)

\requirement{CC:0059.01.04.11.008}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Profile (2 bytes)

\requirement{CC:0059.01.04.11.009}{4}

This field is used to advertise the profile of the actual association group. Refer to Section 3.2.8.3.2 and Table 3.36. This field MUST be encoded according to Table 3.36.

Reserved

\requirement{CC:0059.01.04.11.00A}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Event Code (2 bytes)

\requirement{CC:0059.01.04.11.00B}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

3.2.8.8. Association Group Command List Get¶

This command is used to request the commands that are sent via a given association group.

\requirement{CC:0059.01.05.11.001}{0}

The Association Group Command List Report MUST be returned in response to this command.

\requirement{CC:0059.01.05.11.002}{0}

This command MUST NOT be issued via multicast addressing.

A receiving node MUST NOT return a response if this command is received via multicast addressing. The Z-Wave Multicast frame, the broadcast NodeID and the Multi Channel multi-End Point destination are all considered multicast addressing methods.

Table 3.33 Association Group Command List Get¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_COMMAND_LIST_GET (0x05)
Allow cache	Reserved
Grouping Identifier

Allow Cache (1 bit)

This field indicates that a Z-Wave Gateway device is allowed to intercept the request and return a cached response on behalf of the specified target.

\requirement{CC:0059.01.05.11.003}{0}

If this bit is not set to 1, a Z-Wave Gateway device MUST forward the request to the specified target.

\requirement{CC:0059.01.05.12.001}{0}

A requesting node SHOULD allow caching to save network bandwidth.

\requirement{CC:0059.01.05.11.004}{0}

A Z-Wave Gateway device MUST cache information for all nodes; also listening nodes. This will save network bandwidth.

\requirement{CC:0059.01.05.11.005}{4}

A Z-Wave Gateway device MUST forward the request if it does not hold cached information for the specified target. The Z-Wave Gateway device MUST cache the data returned.

Reserved

\requirement{CC:0059.01.05.11.006}{0}

This field MUST be set to 0 by a sending node and MUST be ignored by a receiving node.

Grouping Identifier (1 byte)

This field is used to specify the requested association group identifier.

\requirement{CC:0059.01.05.12.002}{0}

A node that receives an unsupported Grouping Identifier SHOULD return information relating to Grouping Identifier 1.

3.2.8.9. Association Group Command List Report¶

This command is used to advertise the commands that are sent via an actual association group.

Table 3.34 Association Group Command List Report¶
7	6	5	4	3	2	1	0
Command Class = COMMAND_CLASS_ASSOCIATION_GRP_INFO (0x59)
Command = ASSOCIATION_GROUP_COMMAND_LIST_REPORT (0x06)
Grouping Identifier
List Length
Command Class 1 (1 or 2 bytes)
Command 1
…
Command Class N (1 or 2 bytes)
Command N

Grouping Identifier (1 byte)

This field is used to advertise the actual association group identifier.

List Length (1 byte)

This field advertises the length in bytes of the command list (Command Class and Command fields).

Command Class and Command

\requirement{CC:0059.01.06.13.001}{0}

Command Classes MAY be normal or extended Command Classes.

Normal Command Classes are represented as one byte while extended Command Classes are represented as two bytes. Thus, a command list entry (command class + command) is either 2 or 3 bytes long.

The receiving node must parse individual command list entries to determine if the individual Command Class is a normal or an extended Command Class.

The first byte of normal command classes is in the range 0x20 – 0xEE, while the first byte of extended command classes is in the range 0xF1 – 0xFF.

\requirement{CC:0059.01.06.11.001}{0}

A sending node MUST NOT add any command payload in this field.

\requirement{CC:0059.01.06.11.002}{0}

Command Classes already containing destination NodeID such as Wake Up Command Class MUST NOT be listed in the Association Group Command List Report. This also means that the Wake Up Command Class MUST NOT be covered by the Lifeline association group.