Combines multiple compatible items as members of one group. Properties and methods applied to the group apply to each of the members.  Items within a group are collectively known as group members.  Group members are listed as request channel topics (such as, glp/0/{SID}/rq/dev/cm/8/if/light/0), as shown in the example below.

An IAP group can map to an edge protocol group or other multicast addressing methods, but IAP does not require a specific implementation.  However, it is assumed that operations applied to a group are applied to all group members in rapid succession, near simultaneous if possible.  The edge processor is responsible for implementing IAP groups and for acting upon actions or changes made through a group as efficiently as possible.

A tool can invoke actions on the members through the group’s do topic, and can make an assignment to the group as if the assignment was made to each member.  

Group Characteristics

IAP imposes few limitations on groups. However, some segments may impose limitations, which are reported in the limitations property of the segment About object.  

• The number of groups is not limited in IAP, neither is the number of members within a group. 

• The same item, such as a particular edge device, can be a member of zero, one or more groups. 

• One group can contain members of different types, such as device interface blocks and scenes, or other groups.  

• Groups can be nested, but cannot be self-referencing.  

• Nested group constructs can create loops. Applications should be written to avoid loop constructs.  

• Members are unique within a group; you cannot add the same member twice.

• All members must be accessible by the same edge server which hosts the group. 

• For groups that contain different types of members, the rule is that all is acceptable so long as all members can accept whatever will be applied to the group.

• All group members are listed as request channel topics.

• Edge servers do not generally reject an incompatible group member, as it cannot know the operations that will be applied to the group.  However, one edge server could accept only certain member types, while another could report an error when an operation cannot be applied.

• The group member list can be created or updated without all the members actually existing.  However, all members must exist, and must reference suitable objects, when the group is being provisioned with the self.provision action or with the provision property of the self.create action.

• A group can be deprovisioned even if some members do not exist at that time. An edge server might issue a warning in this case, but should still deprovision the group.

• A group must be provisioned before it can be used to apply data or actions to its members. It can be deprovisioned, and once it is in the unprovisioned state, data or actions can no longer be applied to its members.

• Application of data or action to a group may fail for some but not all members. Errors in relation to individual members, such as an unresponsive device, are reported with the affected device’s status and error or warning diagnostics in the event channel, but are not considered fatal: the group operation continues with the remaining members.

• Rollback does not occur on partial or complete group failure. When one group assignment changes 10 light blocks from 20% to 80% brightness level and two members are unresponsive, the remaining eight will be at 80%.

Group Examples

The edge server reports a group's current configuration with the group configuration object in the feedback channel. The following example shows how you can make changes to individual devices or to an entire group (Notice that the members are listed as request channel topics.):

Group objects can themselves be created, deleted, provisioned, deprovisioned and repaired.  Members can be added and removed.  These operations are also implemented with actions on the group’s do topic. To distinguish actions applied to the group from those applied to the group’s members, actions affecting the group itself are prefixed with “self.” (including the period).

The previous example illustrated how a group can be used to provision all its members. This example shows how the group itself can be provisioned:

The group actions are self.provision, self.deprovision, self.create, self.delete, self.add, self.remove, self.repair.  For example, the following sequence of self.create, self.add, and self.provision actions constructs the group shown in our first example on this page:

IAP vs Protocol Groups

Many control protocols, such as LonTalk or Control-M, support a protocol concept called “groups,” where each device typically is limited to G concurrent group memberships. N can be as little as 0, 1 (Control-M) or 15 (LonTalk), and will probably always be a finite number.

Whatever a particular device’s group limit G might be, IAP group membership might exceed G sooner or later.

Whenever a member cannot be added to a group due to any limitation or error condition, such as a violation of the acceptable maximum group count G, the processor yields an error when executing “add” on .../do.

However, processors may also excel and surpass some of the end-device protocol’s limitations:

• Nothing requires that an IAP group must match a protocol group. Other protocol resources might be available to implement IAP group membership. Candidates include subnet, site or network IDs, or network variable selectors.
• While it is desirable that a group’s value assignment has near simultaneous effect, it might be better to switch one light after another (“trickle switching”) than not switching at all.
• End-device protocol addressing modes might be automatically optimized over time. For example, when an item is member of 3 groups but supports only one (G=1), conceivably the processor will match this to the first group added in IAP, group A. It might accept trickle-switching for the other groups, B and C.

• The same processor might monitor the usage of groups A, B and C. Perhaps B is used more frequently than A or C, so the processor might want to move that light into the protocol group B.

IAP groups can also include other groups. While it is likely that a protocol processor can map one group A to one suitable multicast address for use with that protocol, and another group B to another multicast address, it may not be possible to define A such that it automatically includes B. One solution would be to trickle-switch in groups: first switch group A in one multicast, then (or with a simultaneous transaction) switch group B in another multicast.

Group Object Properties

Each group has its own unique HANDLE, which is part of the group’s topic. Each group object has the following properties: