Skip to content

Device Groups~

Allow devices to share values and control entire groups of devices

A framework to allow multiple devices to be in a group with values such as power, light color, color temperature, brightness, PWM values, sensor values and more, all shared with other devices in the group. For example, with multiple lights in a device group, light settings can be changed on one light and the settings will automatically be changed on other lights. Dimmer switches could be in a device group with lights and that dimmer switch could control the power, brightness and colors of all the lights in the group. Multiple dimmer switches could be in a device group to form a 3-way/4-way dimmer switch.

UDP multicasts, followed by UDP unicasts if necessary, are used to send updates to all devices so updates are fast. There is no need for an MQTT server but all the devices in a group must be on the same multicast network. The multicast address and port are specified at compile time with the DEVICE_GROUPS_ADDRESS (default = 239.255.250.250) and DEVICE_GROUPS_PORT (default = 4447) macros respectively.

To enable device groups, execute command: SetOption85 1. All devices in a group must be running firmware with device group support and have device groups enabled.

Operation~

The device group name is set with the DevGroupName command (GroupTopic prior to v8.2.0.3). If a device group name is not set for a group, the MQTT group topic is used (with the device group number appended for device group numbers > 1). All devices in the same multicast network with the same device group name are in the same group. Some modules may define additional device groups. For example, if Remote Device Mode is enabled, the PWM Dimmer module defines three devices groups.

The items sent and received from the group are selected with the DevGroupShare command. By default all items are sent and received. An example of when the DevGroupShare command would be used is when you have a group of lights that you control with a dimmer switch and home automation software. You want the dimmer switch to be able to control all items. The home automation software controls each light individually. When it controls the whole group, it actually sends command to each light in the group. If you use the home automation software to turn an individual light on or off or change it's brightness, color or scheme, you do not want the change to be replicated to the other lights. In this case, you would set the incoming and outgoing item masks to 0xffffffff (all items) on the dimmer switch (DevGroupShare 0xffffffff,0xffffffff) and set the incoming item mask to 0xffffffff and outgoing item mask to 0 on all the lights (DevGroupShare 0xffffffff,0).

By default, the state of all relays, light settings, etc, are sent to and received from device group 1. To enable each relay (or light channels if option 68 is enabled) to be in a separate device group, enable option 88 (SetOption88 1). When option 88 is enabled, the DevGroupTie sets which relay each device group is tied to. Each device group can only be tied to a single relay. By default, relay 1 is tied to device group 1 (relay 1 updates are sent to/received from device group 1), device 2 is tied to device group 2, device 3 is tied to device group 3 and device 4 is tied to device group 4. If a device group is only to be used by DevGroupSend to send updates to a device group, tie it to device 0.

To implement a device group with lights that change color in sequence (colors move progressively from light to light), use the SequenceOffset command to specify the offset of each light from the master. If your devices have friendly names or MQTT topics that end in the number of the light, SequenceOffset1 can automatically set the offset based on the friendly name/MQTT topic. Once the sequence offset is set, each light will delay light channel changes by the specified number of updates. For example, if you have three lights with friendly names Light1, Light2 and Light3, you can use the SequenceOffset1 command to set the sequence offsets. When you set the color on Light1 to red, then to green and then to blue, the color on Light2 will be green and the color on Light3 will be red. When you set the color on Light1 back to red, the color on Light2 will change to blue and the color on Light3 will change to green.

When a device reboots or looses network connectivity, it requests the current status from device group members when it reconnects. There are times when devices in a device group may be set to a mix of power states, colors, brightnesses, etc. via automation software. For example, you may have a scene that sets the lights in the group to different colors. In this case, the devices in the group should not send light channel information until the color is changed on one of the dimmer switches/masters. To indicate that devices in a device group currently have one or more items that should not be kept in sync, publish/execute the DevGroupSend command with the item value prefixed with N on one of the devices that includes the item in its outgoing share mask. For example, the command DevGroupSend 224=NFF0000 executed on a dimmer switch in the group would set the color to red on the dimmer switch and inform the group that light channel information is not to be shared. You can then set the colors on the lights in the group to assorted colors and the dimmer switch will not change them. Once you set the color on the dimmer switch again (either with the Color command or with DevGroupSend without the N prefix), the syncing will resumt and the colors on the lights will be changed to the that color. You can directly control which items are not shared until they are changed using the DevGroupSend command No Status Share (129) item.

Troubleshooting~

If no values seem to be shared between devices, perform the following checks:

  • Enter the commandSetOption85 on all devices in the group and make sure the result is ON on all devices.
  • Enter the command DevGroupName on all devices in the group and make sure the result for device group 1 is the exact same (case-sensitive) name on all devices.
  • Enter the command DevGroupShare -1,-1 on all devices in the group to enable sharing of all items.
  • Enter the command DevGroupSend 128=1 on one device in the group. If the power turns on on the other devices, the device groups feature is working.
  • Enter the command DevGroupStatus on all devices in the group. If you do not see all the other devices in the group listed as members, multicast packets are not being received by the devices. Check the network infrastructure that connects the devices together to make sure multicasts are enabled are not being filtered.

Commands~

Command Parameters
DevGroupName<x> 0 = clear device group <x> name and restart
<value> = set device group name and restart.\
If a device group name is not set for a group, the MQTT group topic (GroupTopic) is used (with the device group number appended for device group numbers > 1).
DevGroupSend<x> <item> = <value>[ ...] = send an update to device group <x>. The device group name must have been previously set with DevGroupName<x>. Multiple item/value pairs can be specified separated by a space. Spaces in <value> must be escaped with a backslash (\). The message sent is also processed on the local device as if it had been received from the network.

For items with numeric values, <value> can be specified as @<operator>[<operand>] to send a value after performing an operation on the current value. <operator> can be + (add), - (subtract), ^ (invert), & (bitwise AND) or | (bitwise OR). If <operand> is not specified, it defaults to 0xffffffff for the invert operator and 1 for other operators.

To indicate that an item should not be shared with the group until changed again, prefix the value with N.

3 = Light fade (0 = Off, 1 = On)
4 = Light speed (1..40)
5 = Light brightness (0..255)
6 = Light Scheme
7 = Light fixed color (0 = white (using CT channels), other values according to Color)
8 = PWM dimmer low preset (0..255)
9 = PWM dimmer high preset (0..255)
10 = PWM dimmer power-on brightness (0..255)
128 = Relay Power - bitmask with bits set for relays to be powered on. The number of relays can be specified in bits 24 - 31. If the number of relays is not specified, only relay 1 is set
129 = No Status Share - DevGroupShare bitmask indicating which items should not be shared until changed.
192 = Event - event name and arguments
193 = Command - command and arguments
224 = Light channels - comma separated list of brightness levels (0..255) for channels 1 - 5 (e.g. 255,128,0,0,0 will turn the red channel on at 100% and the green channel on at 50% on an RBG light) or hex color value (#RRGGBB, #RRGGBBWW, etc.)

Examples:
DevGroupSend 4=90 128=1 - send an update to set the light brightness to 90 and turn relay 1 on.
DevGroupSend 193=Buzzer\ 2,3 - send the Buzzer 2,3 command.
DevGroupSend 6=@+ 4=@-10 - set the next fixed color and decrease the brightness by 10.
DevGroupSend 128=@^ - toggle all the relays.
DevGroupSend 224=NFF0000 - set the color to red locally and inform the group that light channel information is not to be shared until changed.
DevGroupSend 129=@\|18 - do not share light brightness or channel status until changed.
DevGroupShare <in>,<out> = set incoming and outgoing shared items (default = 0xffffffff,0xffffffff)
<in> and <out> are bit masks where each mask is the sum of the values for the categories (listed below) to be shared. For example, to receive only power (1), light brightness (2) and light color (16) and send only power (1), enter the command DevGroupShare 19,1.

1 = Power
2 = Light brightness
4 = Light fade/speed
8 = Light scheme
16 = Light color
32 = Dimmer settings (presets)
64 = Event
DevGroupStatus<x> Show the status of device group <x> including a list of the currently known members.
DevGroupTie<x> <relay> = Tie the relay to the device group <x>. Only applies when option 88 is enabled.
SequenceOffset<x> 0..255 = set device group color sequence offset. Color updates received from device group will be delayed by the specified number of updates.
x = 0..2
0 = set offset to <value>
1 = set offset to friendly name 1 ending digits + <value> [default -1]
2 = set offset to MQTT topic ending digits + <value> [default -1]
Example.: For friendly name of Light4, SequenceOffset1 will set sequence offset to 3; SequenceOffset1 2 will set offset to 6.