1
Physical light group and virtual light group
Li Shuzhen edited this page 2025-11-24 16:55:28 +08:00

Physical light group

Physical light group is a group of BLE mesh lights that have a physical group address. The physical light group address is allocated by Xiaomi central hub gateway or the device that runs a built-in central hub gateway.

When setting a property of a physical light group, the command message is first sent to the central hub gateway from Mi Home APP. Then the central hub gateway sends only one message to the group address and all mesh devices having the same group address will receive this command message.

when a property value of a physical light group is changed, the central hub gateway reports a properties_changed message whose did field is set to the light group did to the MIoT service cloud and publishes the message to the gateway's MQTT broker inside. The client that subscribes the light group properties_changed message from the MIoT cloud broker or the local gateway broker will receive the message and update the light group property value.

There is no user interface to show whether a light group is a physical light group. The prerequisites for forming a physical light group are that the lights must be BLE mesh devices which support the physical group address, and the lights' BLE mesh gateway must be a central hub gateway.

Virtual light group

Devices in a virtual light group are merely aggregated for display in the Mi Home APP. They do not share a common physical group address. When setting a property of a virtual light group, the command message is sent to each device in the group individually. The devices will update their own property value and report the properties_changed messages separately to the MIoT cloud. The MIoT cloud will aggregate the property values of all devices in the group and NOT publish a properties_changed message whose did field is the virtual light group's did to the MIoT cloud broker. So far, the client that subscribes the virtual light group properties_changed message from the MIoT cloud broker will not receive any message.

Because of the lack of a physical group address, the virtual light group cannot be stored or handled by the central hub gateway. xiaomi_home cannot subscribe the virtual light group properties_changed message from the local gateway broker.

The light group having at least one WiFi light or a BLE mesh light which does not support the physical group address must be a virtual light group. If your BLE mesh gateway is not the central hub gateway, your light group must be a virtual light group.