feat(zigbee): Add Illuminance sensor endpoint #11171

MikaFromTheRoof · 2025-03-24T21:07:49Z

Description of Change

I added a new light sensor endpoint for the zigbee library.
I already informed P-R-O-C-H-Y that I will be creating a pull request for this.

Tests scenarios

I have tested my Pull Request on Arduino-esp32 core v3.2.0-RC2 with a ESP32-C6 board (DFRobot Beetle ESP32-C6) and with Home Assistant and Zigbee2MQTT plugin. The tested code example is part of the pull request.

Formular for calculating lux from raw illuminance

Please check the formular for calculating the lux value from raw illuminance. Typically it should be 10^(lsens_value/10000)-1 as I found on an issue regarding Zigbee2MQTT (see link below). Strangely enough for me testing the code with Zigbee2MQTT, the plugin seems to rather calculate the lux value with 10^(lsens_value/10000), so without the "-1" at the end...

New macro for default light sensor config

I added a new macro for the default light sensor config at the beginning of ZigbeeLightSensor.h. This works as it is, but the macro rather be added to esp-zigbee-sdk/components/esp-zigbee-lib/include/ha/esp_zigbee_ha_standard.h if possible

Related links

Source for lux calculation formular

CLAassistant · 2025-03-24T21:07:56Z

All committers have signed the CLA.

github-actions · 2025-03-24T21:08:29Z

	Warnings
⚠️	Some issues found for the commit messages in this PR: the commit message `"Add comment for macro"`: summary looks empty type/action looks empty the commit message `"Added Zigbee light sensor"`: summary looks empty type/action looks empty the commit message `"Some last corrections"`: summary looks empty type/action looks empty the commit message `"Update Zigbee_Illuminance_Sensor.ino"`: summary looks empty type/action looks empty the commit message `"Update keywords.txt"`: summary looks empty type/action looks empty Please fix these commit messages - here are some basic tips: follow Conventional Commits style correct format of commit message should be: `<type/action>(<scope/component>): <summary>`, for example `fix(esp32): Fixed startup timeout issue` allowed types are: `change,ci,docs,feat,fix,refactor,remove,revert,test` sufficiently descriptive message summary should be between 10 to 72 characters and start with upper case letter avoid Jira references in commit messages (unavailable/irrelevant for our customers) `TIP:` Install pre-commit hooks and run this check when committing (uses the Conventional Precommit Linter).

👋 Hello MikaFromTheRoof, we appreciate your contribution to this project!

📘 Please review the project's Contributions Guide for key guidelines on code, documentation, testing, and more.

🖊️ Please also make sure you have read and signed the Contributor License Agreement for this project.

Click to see more instructions ...

This automated output is generated by the PR linter DangerJS, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.

DangerJS is triggered with each push event to a Pull Request and modify the contents of this comment.

Please consider the following:
- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.
- Danger is not a substitute for human code reviews; it's still important to request a code review from your colleagues.
- Resolve all warnings (⚠️ ) before requesting a review from human reviewers - they will appreciate it.
- To manually retry these Danger checks, please navigate to the Actions tab and re-run last Danger workflow.

Review and merge process you can expect ...

We do welcome contributions in the form of bug reports, feature requests and pull requests.

1. An internal issue has been created for the PR, we assign it to the relevant engineer.
2. They review the PR and either approve it or ask you for changes or clarifications.
3. Once the GitHub PR is approved we do the final review, collect approvals from core owners and make sure all the automated tests are passing.
- At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.
4. If the change is approved and passes the tests it is merged into the default branch.

Generated by 🚫 dangerJS against d377a17

P-R-O-C-H-Y

Hi @MikaFromTheRoof Thank you for bringing up this PR, making the illuminance sensor available for everyone :)

We suggest to change the name of the class from ZigbeeLightSensor to ZigbeeIlluminanceSensor, as it's more detailed and you can easily read what it does, as also the clusters are Illuminance. So please change the naming if you agree.

MikaFromTheRoof · 2025-03-25T20:44:47Z

Hi @MikaFromTheRoof Thank you for bringing up this PR, making the illuminance sensor available for everyone :)

We suggest to change the name of the class from ZigbeeLightSensor to ZigbeeIlluminanceSensor, as it's more detailed and you can easily read what it does, as also the clusters are Illuminance. So please change the naming if you agree.

Done!

…-zigbee-sdk

…sp32-light-sensor into pr/11171

P-R-O-C-H-Y

I have took over to do some smaller updates and tested with ZHA. Works well :)
We can go for merge

github-actions · 2025-03-26T08:22:30Z

Memory usage test (comparing PR against master branch)

The table below shows the summary of memory usage change (decrease - increase) in bytes and percentage for each target.

Memory	FLASH [bytes]		FLASH [%]		RAM [bytes]		RAM [%]
Target	DEC	INC	DEC	INC	DEC	INC	DEC	INC
ESP32S3	0	⚠️ +224	0.00	⚠️ +0.03	0	0	0.00	0.00
ESP32S2	0	⚠️ +224	0.00	⚠️ +0.04	0	0	0.00	0.00
ESP32C3	0	0	0.00	0.00	0	0	0.00	0.00
ESP32C6	0	0	0.00	0.00	0	0	0.00	0.00
ESP32H2	0	0	0.00	0.00	0	0	0.00	0.00
ESP32	0	⚠️ +224	0.00	⚠️ +0.04	0	0	0.00	0.00

Click to expand the detailed deltas report [usage change in BYTES]

Target	ESP32S3		ESP32S2		ESP32C3		ESP32C6		ESP32H2		ESP32
Example	FLASH	RAM	FLASH	RAM	FLASH	RAM	FLASH	RAM	FLASH	RAM	FLASH	RAM
libraries/Zigbee/examples/Zigbee_Color_Dimmer_Switch	⚠️ +224	0	⚠️ +224	0	0	0	0	0	0	0	⚠️ +224	0
libraries/Zigbee/examples/Zigbee_Gateway	⚠️ +224	0	⚠️ +224	0	0	0	-	-	-	-	⚠️ +224	0
libraries/Zigbee/examples/Zigbee_On_Off_Switch	⚠️ +224	0	⚠️ +224	0	0	0	0	0	0	0	⚠️ +224	0
libraries/Zigbee/examples/Zigbee_Range_Extender	⚠️ +224	0	⚠️ +224	0	0	0	0	0	0	0	⚠️ +224	0
libraries/Zigbee/examples/Zigbee_Thermostat	⚠️ +224	0	⚠️ +224	0	0	0	0	0	0	0	⚠️ +224	0
libraries/Zigbee/examples/Zigbee_Analog_Input_Output	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_CarbonDioxide_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Color_Dimmable_Light	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Contact_Switch	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Dimmable_Light	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Illuminance_Sensor	-	-	-	-	-	-	-	-	-	-	-	-
libraries/Zigbee/examples/Zigbee_OTA_Client	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Occupancy_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_On_Off_Light	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Pressure_Flow_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Scan_Networks	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Temp_Hum_Sensor_Sleepy	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Temperature_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Vibration_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor	-	-	-	-	-	-	0	0	0	0	-	-
libraries/Zigbee/examples/Zigbee_Window_Covering	-	-	-	-	-	-	0	0	0	0	-	-

github-actions · 2025-03-26T08:25:52Z

Test Results

76 files 76 suites 12m 45s ⏱️
38 tests 38 ✅ 0 💤 0 ❌
241 runs 241 ✅ 0 💤 0 ❌

Results for commit d377a17.

♻️ This comment has been updated with latest results.

SuGlider · 2025-03-27T03:04:36Z

libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/Zigbee_Illuminance_Sensor.ino

+    // conversion into zigbee raw illuminance value (typically between 0 in darkness and 50000 in direct sunlight)
+    // depends on the value range of the raw analog sensor values and will need calibration for correct lux values
+    // for demonstration purpose map the 12-bit ADC value (0-4095) to Zigbee illuminance range (0-50000)
+    int lsens_illuminance_raw = map(lsens_analog_raw, 0, 4095, 0, 50000);


would it be nicer to set the 50,000 limit as a #define ... - it is used latter in the code.

SuGlider · 2025-03-27T03:04:50Z

libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/Zigbee_Illuminance_Sensor.ino

+  zbIlluminanceSensor.setPowerSource(ZB_POWER_SOURCE_MAINS);
+
+  // Set minimum and maximum for raw illuminance value (0 min and 50000 max equals to 0 lux - 100,000 lux)
+  zbIlluminanceSensor.setMinMaxValue(0, 50000);


would it be nicer to set the 50,000 limit as a #define ... ?

SuGlider

minor detail about the example.

MikaFromTheRoof added 3 commits March 24, 2025 20:11

Added Zigbee light sensor

082762d

Add comment for macro

8fc75db

Some last corrections

6d7b544

MikaFromTheRoof changed the title ~~Added new light sensor endpoint for Zigbee library~~ feat: added new light sensor endpoint for Zigbee library Mar 24, 2025

MikaFromTheRoof changed the title ~~feat: added new light sensor endpoint for Zigbee library~~ Added new light sensor endpoint for Zigbee library Mar 24, 2025

P-R-O-C-H-Y added the Area: Zigbee Issues and Feature Request about Zigbee label Mar 25, 2025

P-R-O-C-H-Y self-requested a review March 25, 2025 08:11

P-R-O-C-H-Y changed the title ~~Added new light sensor endpoint for Zigbee library~~ feat(zigbee): Add Light sensor endpoint Mar 25, 2025

P-R-O-C-H-Y requested changes Mar 25, 2025

View reviewed changes

refactor(zigbee): changed class name to ZigbeeIlluminanceSensor

8a0f8df

P-R-O-C-H-Y changed the title ~~feat(zigbee): Add Light sensor endpoint~~ feat(zigbee): Add Illuminance sensor endpoint Mar 26, 2025

P-R-O-C-H-Y added 6 commits March 26, 2025 09:06

feat(zigbee): Illumanance sensor update

9560a8a

Merge branch 'master' into master

0adf010

fix(zigbee): Change name of macro to avoid possible conflict with esp…

ad7ef1b

…-zigbee-sdk

Update keywords.txt

d7c7e41

Merge branch 'master' of https://github.com/MikaFromTheRoof/arduino-e…

b671041

…sp32-light-sensor into pr/11171

fix(zigbee): Add Illuminance to Cmake file

b22d447

P-R-O-C-H-Y self-assigned this Mar 26, 2025

fix(example): Update Illuminance example

261cb06

P-R-O-C-H-Y approved these changes Mar 26, 2025

View reviewed changes

P-R-O-C-H-Y added the Status: Review needed Issue or PR is awaiting review label Mar 26, 2025

P-R-O-C-H-Y added this to the 3.2.0 milestone Mar 26, 2025

P-R-O-C-H-Y requested a review from me-no-dev March 26, 2025 08:18

me-no-dev approved these changes Mar 26, 2025

View reviewed changes

P-R-O-C-H-Y removed the Status: Review needed Issue or PR is awaiting review label Mar 26, 2025

P-R-O-C-H-Y added the Status: Pending Merge Pull Request is ready to be merged label Mar 26, 2025

pre-commit-ci-lite bot and others added 3 commits March 26, 2025 10:12

ci(pre-commit): Apply automatic fixes

c17ddf6

Update Zigbee_Illuminance_Sensor.ino

b80ad66

ci(pre-commit): Apply automatic fixes

d377a17

SuGlider self-requested a review March 27, 2025 03:01

SuGlider reviewed Mar 27, 2025

View reviewed changes

SuGlider approved these changes Mar 27, 2025

View reviewed changes

me-no-dev merged commit e37435c into espressif:master Mar 27, 2025
56 checks passed

P-R-O-C-H-Y mentioned this pull request Apr 2, 2025

ESP32 Zigbee Ambient light sensor example required #10855

Closed

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(zigbee): Add Illuminance sensor endpoint #11171

feat(zigbee): Add Illuminance sensor endpoint #11171

MikaFromTheRoof commented Mar 24, 2025

CLAassistant commented Mar 24, 2025 •

edited

Loading

github-actions bot commented Mar 24, 2025 •

edited

Loading

P-R-O-C-H-Y left a comment

MikaFromTheRoof commented Mar 25, 2025

P-R-O-C-H-Y left a comment

github-actions bot commented Mar 26, 2025 •

edited

Loading

github-actions bot commented Mar 26, 2025 •

edited

Loading

SuGlider Mar 27, 2025

SuGlider Mar 27, 2025

SuGlider left a comment

feat(zigbee): Add Illuminance sensor endpoint #11171

feat(zigbee): Add Illuminance sensor endpoint #11171

Conversation

MikaFromTheRoof commented Mar 24, 2025

Description of Change

Tests scenarios

Formular for calculating lux from raw illuminance

New macro for default light sensor config

Related links

CLAassistant commented Mar 24, 2025 • edited Loading

github-actions bot commented Mar 24, 2025 • edited Loading

P-R-O-C-H-Y left a comment

Choose a reason for hiding this comment

MikaFromTheRoof commented Mar 25, 2025

P-R-O-C-H-Y left a comment

Choose a reason for hiding this comment

github-actions bot commented Mar 26, 2025 • edited Loading

Memory usage test (comparing PR against master branch)

github-actions bot commented Mar 26, 2025 • edited Loading

Test Results

SuGlider Mar 27, 2025

Choose a reason for hiding this comment

SuGlider Mar 27, 2025

Choose a reason for hiding this comment

SuGlider left a comment

Choose a reason for hiding this comment

CLAassistant commented Mar 24, 2025 •

edited

Loading

github-actions bot commented Mar 24, 2025 •

edited

Loading

github-actions bot commented Mar 26, 2025 •

edited

Loading

github-actions bot commented Mar 26, 2025 •

edited

Loading