Zigbee RUC Lighting

For the sake of brevity, we refer to Realistic Use Cases (RUC) as an abbreviation throughout this discussion.

1 Introduction

This page describes how to quickly handle an On/Off Light Device with On/Off Light Switch.
The project generates a Zigbee Light Device acting as a Router (ZR) and Zigbee Light Switches as End Devices (ED).
It serves as a good introduction for a first approach to a ST Zigbee mesh solution.

2 Functioning

This example demonstrates STM32WB application capabilities using the Zigbee network with ST devices to connect switches and light bulbs in different scenarios.
Starting from a basic example where one switch is connected to one light bulb, it is possible to connect multiple switches to the same light bulb, or to connect one switch to multiple light bulbs, along with other combinations, to test the ST Zigbee functionalities.

RUC Lighting
Connectivity Realistic Use Case-Wiki-RUC Lighting.drawio.png

3 Getting started

This project implements an ST Zigbee mesh supporting the Coordinator (ZC), Router (ZR) and End Device (ZED) features.
These features are sufficient to set up a first Zigbee network [1].
The ZED are not Sleepy devices, but it is a possible extension. For more information, see Application Note [2].

3.1 Hardware requirements

P-NUCLEO-WB55[3] and STM32WB5MM-DK[4] are required to set up the demonstration.
For more information, visit STM32WB Development ecosystem.

Connectivity nucleo-description.png
Connectivity STM32WB5MM-Board-Description.png

3.2 Software and system requirements

All the application projects can be found on Github hotspot:

  • Zigbee_Coord
  • Zigbee_Light_Switch
  • Zigbee_Occupancy_Sensor
  • Zigbee_OnOff_Sensor
  • Zigbee_OnOff_Light

For more information to build Zigbee application, visit STM32WB Build Zigbee Project.
To check messages from the board, use any convenient terminal software through the UART Interface, see Wiki: Zigbee Log via UART for more information.

3.3 Install the Zigbee network

To install the RUC example, follow the HowTo Join a Zigbee Network and HowTo bind devices.

4 Zigbee implementation

This example uses the Zigbee cluster On/Off [5] with the following topology:

  • a Gateway as ZC
  • Light switches as ZED with client cluster on P-NUCLEO-WB55 [3]
  • Light bulb as ZR with server cluster on a STM32WB5MM-DK [4]

So, the main topology uses 1 ZC, 2 ZR and 4 ZED, both ZR bound to 2 ZED each.
It is possible to extend devices with Zigbee clusters Level control [6], Color control[7], etc. to add device features.

A crucial point to note is that the server holds the attribute values, that is, the state of the light in this case. If the client wants to know the light's state, it needs to send the command "read the attribute" to the server. When two devices are bound together, they can set up a link where the server sends the state of some attributes when they are modified. These attributes are called reportable. For instance, in a network with 2 switches and one light, if both switches are bound to the light, Switch 1 can turn the light on, and Switch 2 is informed of the change in the light's state.

4.1 Light switch

The client command (switch) sends a message (On/Off/Toggle) to the server (light bulb). The implementation is straightforward and high-level, allowing you to choose the messages delivery method: broadcast, group or unicast. In this example, the message is sent in unicast mode, which requires binding the devices together. This approach enables configuring the reporting process and receiving an acknowledgement from the server.

Find below the code example of the use case and the different layer to understand and modify it.

Source code SW Layers
Connectivity Zigbee Realistic Use Case-Wiki-Lighting-Light Switch SW code.png
Connectivity Zigbee Realistic Use Case-Wiki-Lighting-Light Switch SW Layers.png

4.2 Light bulb

After reception of a command from a client, an appropriate callback function is executed by the server.
If there is an attribute modification, the server sends this modification to each client according to the report configuration in the local binding table.

Find below the code example of the use case and the different layer to understand and modify it.

Source code SW Layers
Connectivity RUC-source code exemple.png
Connectivity Zigbee Realistic Use Case-Wiki-Overview-RUC SW Layers.png

4.3 Binding and report process

To manage many configurations, attribute reports are used to troubleshoot issues.
So, each time a client binds to a server, a configuration report is created to notify the client of the attribute modification.
For more information, see Wiki: Zigbee Binding.
Find below the Binding process used in this example.

Binding process
Connectivity Realistic Use Case-Wiki-Lighting Binding Process.png

In the case of multiple clients, the Report attribute is used to maintain a coherence between each client when the state of the light is changed on the server.
Find below the Report attribute process for two clients:

Report attribute process
Connectivity Realistic Use Case-Wiki-Lighting Report attribute Process.png

4.4 Retry process

When a client sends a command, there are three possible situations:

  • Nominal case: Everything works fine, and the client receives successful acknowledgement from the server.
  • Error case 1: The client receives an acknowledgement from the server, but with failure that implies an error in processing the command.
  • Error case 2: The client does not receive any response from server, indicating a communication issue.

To make it more reliable, a “retry” process was created when a Zigbee command from client fails.
As explained before, for all applications, all the commands are sent in unicast. Once the command is sent, the server responds with an acknowledgement. If this one includes a failure message, the message is resent to the server.

Find below the retry process and the flow chart implemented in source code:

Retry process
Connectivity Realistic Use Case-Wiki-Lighting cmd Retry process.png
Flow chart
Connectivity Realistic Use Case-Wiki-Lighting cmd Retry Process - Flow chart..png

By implementing this mechanism, the number of failed commands significantly decreases.

5 Possible extension

From this use case, some extensions are possible:

  • Add several Light Bulbs (multi-server) to observe when clients send commands and server behavior.
  • Add dimmable light and switch.
  • Add color control light and switch.
  • Add PIR occupancy sensor to light on/off automatically.

Below, the example shows an extension with a PIR sensor and dimmable switch:

RUC Lighting extension
Connectivity Realistic Use Case-Wiki-RUC Lighting extension.png

6 Tests and results

To stress the system and verify its proper functioning, a series of tests has been conducted.

Test Passed/Failed
Adding a server (ZR) and getting current service value Passed
Adding a client (ZED) and getting current service value Passed
Detecting and handling the case of report not received Passed
Correcting the issue of report not received by reading service value Passed
Same Zigbee cmd from multiple clients at the same time Passed
Different Zigbee cmd from multiple clients at the same time Passed
Overloading the system with sending Zigbee cmd on time (with PIR) Passed
Latency test Passed
Distance (3-hops) Passed
Endurance time (7 days) Passed
Remove Coordinator Passed

7 Acronyms and definitions

Term Definition
ZC Zigbee Coordinator
ZR Zigbee Router
ZED Zigbee End Device
RUC Realistic Use Case
PIR Passive Infra-Red sensor, motion detectors

8 References