{"id":23541302,"url":"https://github.com/kampi/beelight","last_synced_at":"2026-04-25T23:37:04.948Z","repository":{"id":268315022,"uuid":"903881861","full_name":"Kampi/BeeLight","owner":"Kampi","description":"Zigbee environment sensor device with Zigbee2MQTT support.","archived":false,"fork":false,"pushed_at":"2026-03-21T12:45:49.000Z","size":76410,"stargazers_count":13,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-03-22T03:13:18.217Z","etag":null,"topics":["electronics","home-assistant","home-automation","kibot","kicad","ncs","nrf-connect-sdk","nrf54","nrf54l15","pcb","zephyr","zigbee","zigbee-board","zigbee-herdsman","zigbee-protocol","zigbee2mqtt"],"latest_commit_sha":null,"homepage":"https://www.kampis-elektroecke.de","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kampi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["Kampi"]}},"created_at":"2024-12-15T19:47:38.000Z","updated_at":"2026-03-21T12:37:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"79bab39d-7362-46db-8a81-a6591bbbf179","html_url":"https://github.com/Kampi/BeeLight","commit_stats":null,"previous_names":["kampi/zigbee-lightsensor","kampi/beelight"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Kampi/BeeLight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kampi%2FBeeLight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kampi%2FBeeLight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kampi%2FBeeLight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kampi%2FBeeLight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kampi","download_url":"https://codeload.github.com/Kampi/BeeLight/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kampi%2FBeeLight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electronics","home-assistant","home-automation","kibot","kicad","ncs","nrf-connect-sdk","nrf54","nrf54l15","pcb","zephyr","zigbee","zigbee-board","zigbee-herdsman","zigbee-protocol","zigbee2mqtt"],"created_at":"2024-12-26T05:15:19.692Z","updated_at":"2026-04-25T23:37:04.941Z","avatar_url":"https://github.com/Kampi.png","language":"JavaScript","funding_links":["https://github.com/sponsors/Kampi"],"categories":[],"sub_categories":[],"readme":"# BeeLight - Zigbee based light \u0026 environment sensor for Home Automation\n\n[![License](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://opensource.org/license/gpl-3-0/)\n[![PCB](https://github.com/Kampi/BeeLight/actions/workflows/pcb.yaml/badge.svg)](https://www.github.com/Kampi/BeeLight/actions/workflows/pcb.yaml)\n[![Documentation](https://img.shields.io/badge/Documentation-HTML-007ec6?longCache=true\u0026style=flat\u0026logo=asciidoctor\u0026colorA=555555)](https://kampi.github.io/BeeLight/)\n\n## Table of Contents\n\n- [BeeLight - Zigbee based light \\\u0026 environment sensor for Home Automation](#beelight---zigbee-based-light--environment-sensor-for-home-automation)\n  - [Table of Contents](#table-of-contents)\n  - [About](#about)\n    - [Technical features](#technical-features)\n  - [Before you start](#before-you-start)\n    - [PCB](#pcb)\n    - [Firmware](#firmware)\n      - [Build the firmware](#build-the-firmware)\n      - [Flash the firmware](#flash-the-firmware)\n      - [Generate the production config for the device](#generate-the-production-config-for-the-device)\n        - [Using west](#using-west)\n        - [Using the command line](#using-the-command-line)\n    - [Housing](#housing)\n    - [Zigbee](#zigbee)\n      - [Standard clusters](#standard-clusters)\n      - [Custom cluster](#custom-cluster)\n      - [Zigbee Dongle](#zigbee-dongle)\n      - [Install the device to Zigbee2MQTT](#install-the-device-to-zigbee2mqtt)\n      - [Using the NCS Zigbee Shell](#using-the-ncs-zigbee-shell)\n  - [Directory structure](#directory-structure)\n  - [Resources](#resources)\n  - [Maintainer](#maintainer)\n\n## About\n\nOpen-Source Zigbee-based light and environmental sensor with [Zigbee2MQTT](https://www.zigbee2mqtt.io/) support for your Home Automation (e.g., Home Assistant).\n\n![Rendering](docs/images/Rendering.png)\n\n### Technical features\n\n- Cutting-edge MCU module with an nRF54L, running Zephyr\n- Powered by a single coin cell\n- Can measure\n  - Temperature\n  - Humidity\n  - Pressure\n  - IAQ\n  - CO2 equivalent\n  - VOC equivalent\n  - Light intensity\n  - Battery voltage\n- Small housing (40x42x20 mm)\n- Very basic electronic → Can be assembled by hand very easily\n- Zigbee2MQTT compatibility\n\n![Block diagram](docs/images/Block%20diagram.png)\n\n## Before you start\n\nThe project directory contains the hardware as a [KiCad 9](https://www.kicad.org/download/) project, the firmware and the Zigbee2MQTT configuration. You can check it out with Git:\n\n```sh\ngit clone https://github.com/Kampi/BeeLight\ncd BeeLight\ngit submodule update --init --recursive\ncd firmware/app\nwest init -l .\nwest update\n```\n\nYou also need [nrfutil](https://www.nordicsemi.com/Products/Development-tools/nRF-Util) and the `nrf5sdk-tools` to flash the production configuration to the sensor. First install `nrfutil` and then run the following command to install the SDK tools:\n\n```sh\nnrfutil install nrf5sdk-tools\n```\n\n### PCB\n\nThe project uses [Kibot](https://github.com/INTI-CMNB/KiBot) to automatically generate all required output data. After installing it you can execute the following command to run it:\n\n```sh\ncd hardware\n./kibot-launch.sh\n```\n\nAs an alternative you can run it via CI/CD in GitHub.\n\n\u003e **NOTE**\n\u003e You have to provide a Mouser API key with a variable called `MOUSER_KEY` to make use of the KiCost feature in the Kibot job.\n\u003e\n\u003e **NOTE**\n\u003e The programming connector is optional and can be left out or unsoldered after flashing the device.\n\n### Firmware\n\n#### Build the firmware\n\nThe firmware can be built with the following command:\n\n```sh\ncd firmware/app\nwest build --build-dir build . --pristine --board beelight@1/nrf54l15/cpuapp -- -DNCS_TOOLCHAIN_VERSION=NONE -DEXTRA_CONF_FILE=config/debug.conf -DBOARD_ROOT=.\n```\n\nYou also need a Zigbee network to test and integrate the device. I use [Zigbee2MQTT](https://www.zigbee2mqtt.io/) running on a Raspberry Pi which allows me to connect my Zigbee network with my Home Automation.\n\n\u003e **NOTE**\n\u003e I do not support other Zigbee networks (like [ZHA](https://www.home-assistant.io/integrations/zha/)). The Zigbee standard allows you to connect the device with all other networks but I can't deliver a functional integration for these networks. You have to do it on your own!\n\n#### Flash the firmware\n\nAfter building the firmware you can run\n\n```sh\nwest flash\n```\n\nto flash the firmware into the module.\n\n\u003e **NOTE**\n\u003e For some reason the current consumption stays high after flashing. I recommend a complete power cycle after flashing to make sure the device is consuming the lowest current possible.\n\n#### Generate the production config for the device\n\n##### Using west\n\nYou can run the command `west upload_config` to build and upload your configuration to the device automatically.\n\n##### Using the command line\n\nYou must flash a production config to the device, before you can use it with Zigbee. You can either use the prebuilt config from the project or adjust it according to your needs.\n\n```sh\nnrfutil nrf5sdk-tools zigbee production_config zigbee_config.yml zigbee_config.hex --offset 0x17a000\nnrfjprog --program zigbee_config.hex --verify\n```\n\n\u003e **NOTE**\n\u003e The offset `0x17a000` is taken from the `PM_ZBOSS_PRODUCT_CONFIG_OFFSET` macro in `build/\u003capp\u003e/zephyr/include/generated/pm_config.h`. Also make sure to change `extended_address` in the Zigbee\n\u003e configuration file if you use more than one device!\n\n### Housing\n\nThe housing is optimized for 3D printing and needs ~12 g of filament (PLA). You can find all the needed files in the `3d-printing` directory of this project.\n\n### Zigbee\n\nThe device uses different standard and custom cluster to report the data to the network.\n\n#### Standard clusters\n\n| Cluster | ID |\n| ------- | -- |\n| Temperature | 0x0402 |\n| Pressure | 0x0403 |\n| Rel. Humidity | 0x0405 |\n| Light | 0x0400 |\n\n#### Custom cluster\n\nThe device uses three custom cluster to report `IAQ`, `VOC` and `CO2` to the network. Both clusters have three attributes for `value`, `min_value`, `max_value` and `tolerance`.\n\n| Cluster | ID |\n| ------- | -- |\n| IAQ | 0x1A0A |\n| VOC | 0x1A0B |\n| CO2 | 0x1A0C |\n\n| Attribute | ID |\n| --------- | -- |\n| Value | 0x0000 |\n| Min. Value | 0x0001 |\n| Max. Value | 0x0002 |\n| Tolerance | 0x0003 |\n\n#### Zigbee Dongle\n\nMake sure to use a Zigbee 3 compatible dongle like [SONOFF ZBDongle-E](https://sonoff.tech/product/gateway-and-sensors/sonoff-zigbee-3-0-usb-dongle-plus-e/) and update the firmware to the latest version to prevent issues. You can follow [this](https://dongle.sonoff.tech/sonoff-dongle-flasher/) guide if you use a SONOFF dongle.\n\n#### Install the device to Zigbee2MQTT\n\n\u003e **NOTE**\n\u003e Because it's not possible to use custom clusters with Zigbee2MQTT easily, you must adjust the application directly to use the sensor. Please take a look into the directory `z2m/data/external_converters/example` if you want to check how the modified files look like.\n\n1. Download and install [Zigbee2MQTT](https://github.com/zigbee2mqtt/hassio-zigbee2mqtt)\n2. Copy the external converter from `z2m/data_external_converters` to the `data` directory of your `Zigbee2MQTT` installation\n3. Switch into the directory `.../zigbee2mqtt/node_modules/zigbee-herdsman/dist/zspec/zcl/definition` and open `cluster.js` and add the following code to `exports.Clusters`\n\n```ts\n...\n    msBeelightIAQ: {\n        ID: 6666,\n        attributes: {\n            measuredValue: { ID: 0, type: enums_1.DataType.UINT16 },\n            minMeasuredValue: { ID: 1, type: enums_1.DataType.UINT16 },\n            maxMeasuredValue: { ID: 2, type: enums_1.DataType.UINT16 },\n            tolerance: { ID: 3, type: enums_1.DataType.UINT8 },\n        },\n        commands: {},\n        commandsResponse: {},\n    },\n    msBeelightVOC: {\n        ID: 6667,\n        attributes: {\n            measuredValue: { ID: 0, type: enums_1.DataType.UINT16 },\n            minMeasuredValue: { ID: 1, type: enums_1.DataType.UINT16 },\n            maxMeasuredValue: { ID: 2, type: enums_1.DataType.UINT16 },\n            tolerance: { ID: 3, type: enums_1.DataType.UINT8 },\n        },\n        commands: {},\n        commandsResponse: {},\n    },\n    msBeelightCO2: {\n        ID: 6668,\n        attributes: {\n            measuredValue: { ID: 0, type: enums_1.DataType.UINT16 },\n            minMeasuredValue: { ID: 1, type: enums_1.DataType.UINT16 },\n            maxMeasuredValue: { ID: 2, type: enums_1.DataType.UINT16 },\n            tolerance: { ID: 3, type: enums_1.DataType.UINT8 },\n        },\n        commands: {},\n        commandsResponse: {},\n    },\n...\n```\n\n4. Save the file\n5. Switch to `.../zigbee2mqtt/node_modules/zigbee-herdsman-converters/dist/lib`\n6. Open the file `modernExtend.js` and add the following cluster to the end of the list at the end of the file:\n7. Add\n\n```js\n...\nexports.BeeLight_iaq = BeeLight_iaq;\nexports.BeeLight_co2 = BeeLight_co2;\nexports.BeeLight_voc = BeeLight_voc;\n...\n```\n\n8. Extend the following section\n\n```js\n// #region Measurement and Sensing\nfunction BeeLight_iaq(args = {}) {\n    return numeric({\n        name: \"BeeLight_iaq\",\n        cluster: \"msBeelightIAQ\",\n        attribute: \"measuredValue\",\n        reporting: { min: \"5_MINUTES\", max: \"1_HOUR\", change: 10 },\n        description: \"Measured IAQ value\",\n        unit: \"\",\n        scale: 1,\n        access: \"STATE_GET\",\n        ...args,\n    });\n}\nfunction BeeLight_co2(args = {}) {\n    return numeric({\n        name: \"BeeLight_co2\",\n        cluster: \"msBeelightCO2\",\n        attribute: \"measuredValue\",\n        reporting: { min: \"5_MINUTES\", max: \"1_HOUR\", change: 10 },\n        description: \"Measured CO2 value\",\n        unit: \"ppm\",\n        scale: 1,\n        access: \"STATE_GET\",\n        ...args,\n    });\n}\nfunction BeeLight_voc(args = {}) {\n    return numeric({\n        name: \"BeeLight_voc\",\n        cluster: \"msBeelightVOC\",\n        attribute: \"measuredValue\",\n        reporting: { min: \"5_MINUTES\", max: \"1_HOUR\", change: 10 },\n        description: \"Measured VOC value\",\n        unit: \"ppm\",\n        scale: 1,\n        access: \"STATE_GET\",\n        ...args,\n    });\n}\n...\n```\n\n9. Save the file\n10. Restart Zigbee2MQTT\n\nThe device can now be connected to your Zigbee network and with this to your Home Assistant.\n\n![Zigbee2MQTT](docs/images/Zigbee2MQTT.png)\n![HomeAssistant](docs/images/HomeAssistant.png)\n\n#### Using the NCS Zigbee Shell\n\nYou can test the device by using the NCS Zigbee Shell example and an nRF54DK or an nRF5340DK.\n\n1. Flash the Zigbee Shell example to your board\n2. Execute `nvram disable`\n3. Execute `bdb role zc`\n4. Execute `bdb channel 11`\n5. Execute `bdb start`\n6. Flash the sensor device firmware and the network configuration\n7. Reset the sensor device and start the join procedure\n8. You should get this output from the network coordinator device\n\n```sh\n[00:05:05.648,345] \u003cinf\u003e zigbee_app_utils: Joined network successfully (Extended PAN ID: f4ce36b2d4c06ca0, PAN ID: 0x6057)\n[00:05:24.536,529] \u003cinf\u003e zigbee_app_utils: Device authorization event received (short: 0x02fa, long: 86d79ac5bae41fa3, authorization type: 3, authorization status: 0)\n[00:05:24.536,773] \u003cinf\u003e zigbee_app_utils: Unimplemented signal (signal: 53, status: 0)\n[00:05:24.537,139] \u003cinf\u003e zigbee_app_utils: Device update received (short: 0x02fa, long: 86d79ac5bae41fa3, status: 1)\n```\n\n9. Now you can read the clusters with `zcl attr read \u003cAddress\u003e 10 \u003cCluster\u003e 0x0104 0x0000`\n10. Use `zcl subscribe on \u003cAddress\u003e 10 \u003cCluster\u003e 0x0104 0x00 33 \u003cMin (s)\u003e \u003cMax (s)\u003e` to create a binding for the given cluster\n\n## Directory structure\n\n- `3d-print`: All 3D print-related files\n- `cad`: All relevant 3D models\n- `docs`: All kinds of project documentation like schematics, BOM, etc.\n  - `drawings`: 2D drawings for subcomponents, etc.\n  - `images`: All documentation-relateBd images\n- `hardware`: KiCad project for the PCB\n- `firmware`: Zephyr project for the device firmware\n- `prebuilt`: Prebuilt binaries\n- `z2m`: Zigbee2MQTT-related files\n\n## Resources\n\n- [Adding new Zigbee2MQTT devices](https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html)\n- [Zigbee Cluster Library Specification](https://zigbeealliance.org/wp-content/uploads/2019/12/07-5123-06-zigbee-cluster-library-specification.pdf)\n- [Generating HEX files for Zigbee production configuration](https://docs.nordicsemi.com/bundle/nrfutil/page/nrfutil-nrf5sdk-tools/guides/generating_zigbee_hex.html)\n- [Zigbee Converters](https://github.com/Koenkk/zigbee-herdsman-converters)\n- [KiBot Template](https://github.com/nguyen-v/KDT_Hierarchical_KiBot)\n- [Zigbee Shell](https://docs.nordicsemi.com/bundle/addon-zigbee-r23-latest/page/lib/shell.html#zdo_ieeeaddr)\n\n## Maintainer\n\n- [Daniel Kampert](mailto:DanielKampert@kampis-elektroecke.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkampi%2Fbeelight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkampi%2Fbeelight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkampi%2Fbeelight/lists"}