README.md
View this project on CADLAB.io.

BeeLight - Zigbee based light & environment sensor for Home Automation

Table of Contents


BeeLight - Zigbee based light \& environment sensor for Home Automation


Table of Contents
About
Technical features
Before you start
PCB
Firmware


Build the firmware
Flash the firmware
Generate the production config for the device
Using west
Using the command line

Housing
Zigbee


Standard cluster
Custom cluster
Zigbee Dongle
Install the device to Zigbee2MQTT

Directory structure
Ressources
Maintainer



About

Open-Source Zigbee-based light and environmental sensor with <![CDATA[]]>Zigbee2MQTT<![CDATA[]]> support for your Home Automation with I. e. Home Assistant.



Technical features


Cutting-edge MCU with an nRF54L, running Zephyr
Powered by a single coin cell
Can measure


Temperature
Humidity
Pressure
IAQ
CO2 equivalent
VOC equivalent
Light intensity
Battery voltage

Small housing (40x42 mm)
Very basic electronic → Can be assembled by hand very easily
Zigbee2MQTT compatibility




Before you start

The project directory contains the hardware as a <![CDATA[]]>KiCad 9<![CDATA[]]> project, the firmware and the Zigbee2MQTT configuration. You can check it out with Git:

git clone https://github.com/Kampi/BeeLight
cd BeeLight
git submodule update --init --recursive
cd firmware/app
west init -l .
west update


Run the following commands to install the BSEC2 library:

west config manifest.group-filter +bsec
west update


You also need <![CDATA[]]>nrfutil<![CDATA[]]> 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:

nrfutil install nrf5sdk-tools


PCB

The project uses <![CDATA[]]>Kibot<![CDATA[]]> to automatically generate all required output data. After installing it you can execute the following command to run it:

cd hardware
./kibot-launch.sh


As an alternative you can run it via CI/CD in GitHub.


  
NOTE
  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.
  
  
NOTE
  The programming connector is optional and can be left out or unsoldered after flashing the device.


Firmware

Build the firmware

The firmware can be built with the following command:

cd firmware/app
west build --build-dir build . --pristine --board beelight@1/nrf54l15/cpuapp -- -DNCSTOOLCHAINVERSION=NONE -DEXTRACONFFILE=config/debug.conf -DBOARD_ROOT=.


You also need a Zigbee network to test and integrate the device. I use <![CDATA[]]>Zigbee2MQTT<![CDATA[]]> running on a Raspberry Pi which allows me to connect my Zigbee network with my Home Automation.


  
NOTE
  I do not support other Zigbee networks (like <![CDATA[]]>ZHA<![CDATA[]]>). 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!


Flash the firmware

After building the firmware you can run

west flash


to flash the firmware into the module.


  
NOTE
  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.


Generate the production config for the device

Using west

You can run the command west upload_config to build and upload your configuration to the device automatically.

Using the command line

You 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.

nrfutil nrf5sdk-tools zigbee productionconfig zigbeeconfig.yml zigbeeconfig.hex --offset 0x17a000
nrfjprog --program zigbeeconfig.hex --verify



  
NOTE
  The offset 0x17a000 is taken from build/<app>/zephyr/include/generated/pm_config.h. Also make sure to change extended_address in the Zigbee
  configuration file if you use more than one device!


Housing

The 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.

Zigbee

The device uses different standard and custom cluster to report the data to the network.

Standard cluster




  
Cluster
  
ID




  
Temperature
  
0x0402


  
Pressure
  
0x0403


  
Rel. Humidity
  
0x0405


  
Light
  
0x0400




Custom cluster

The device uses two custom cluster to report IAQ, VOC and CO2 to the network. Both clusters have three attributes for value, min_value, max_value and tolerance.




  
Cluster
  
ID




  
IAQ
  
0x1A0A


  
VOC
  
0x1A0B


  
CO2
  
0x1A0C







  
Attribute
  
ID




  
Value
  
0x0000


  
Min. Value
  
0x0001


  
Max. Value
  
0x0002


  
Tolerance
  
0x0003




Zigbee Dongle

Make sure to use a Zigbee 3 compatible dongle like <![CDATA[]]>SONOFF ZBDongle-E<![CDATA[]]> and update the firmware to the latest version to prevent issues. You can follow <![CDATA[]]>this<![CDATA[]]> guide if you use a SONOFF dongle.

Install the device to Zigbee2MQTT


  
NOTE
  Because it´s not possible to use custom cluster with Zigbee2MQTT easily, so 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.



Download and install <![CDATA[]]>Zigbee2MQTT<![CDATA[]]>
Copy the external converter from z2m/data_external_converters to the data directory of your Zigbee2MQTT installation
Switch into the directory .../zigbee2mqtt/node_modules/zigbee-herdsman-converters/converters
Open the file fromZigbee.js and add the following code before const converters = { ...converters1, ...converters2 }; at the end of the file


const converters3 = {
  BeeLightiaq: {
    cluster: 'msIAQ',
    type: ['attributeReport', 'readResponse'],
    convert: (model, msg, publish, options, meta) => {
      const iaq = msg.data['measuredValue'];
      const tolerance = msg.data['tolerance'];
      const property = (0, utils1.postfixWithEndpointName)('iaq', msg, model, meta);
      return { [property]: iaq };
    },
  },
  BeeLightvoc: {
    cluster: 'msVOC',
    type: ['attributeReport', 'readResponse'],
    convert: (model, msg, publish, options, meta) => {
      const voc = msg.data['measuredValue'];
      const tolerance = msg.data['tolerance'];
      const property = (0, utils1.postfixWithEndpointName)('voc', msg, model, meta);
      return { [property]: voc };
    },
  },
  BeeLightco2: {
    cluster: 'msCO2',
    type: ['attributeReport', 'readResponse'],
    convert: (model, msg, publish, options, meta) => {
      const co2 = msg.data['measuredValue'];
      const tolerance = msg.data['tolerance'];
      const property = (0, utils1.postfixWithEndpointName)('co2', msg, model, meta);
      return { [property]: co2 };
    },
  },
};



Change const converters = { ...converters1, ...converters2 }; to const converters = { ...converters1, ...converters2, ...converters3 };
Save the file
Switch to .../zigbee2mqtt/node_modules/zigbee-herdsman/dist/zspec/zcl/definition
Open the file cluster.js and add the following cluster to the end of the list at the end of the file:


      ...
    },
    msIAQ: {
        ID: 6666,
        attributes: {
            measuredValue: { ID: 0, type: enums1.DataType.UINT16 },
            minMeasuredValue: { ID: 1, type: enums1.DataType.UINT16 },
            maxMeasuredValue: { ID: 2, type: enums1.DataType.UINT16 },
            tolerance: { ID: 3, type: enums1.DataType.UINT8 },
        },
        commands: {},
        commandsResponse: {},
    },
    msVOC: {
        ID: 6667,
        attributes: {
            measuredValue: { ID: 0, type: enums1.DataType.UINT16 },
            minMeasuredValue: { ID: 1, type: enums1.DataType.UINT16 },
            maxMeasuredValue: { ID: 2, type: enums1.DataType.UINT16 },
            tolerance: { ID: 3, type: enums1.DataType.UINT8 },
        },
        commands: {},
        commandsResponse: {},
    },
    msCO2: {
        ID: 6668,
        attributes: {
            measuredValue: { ID: 0, type: enums1.DataType.UINT32 },
            minMeasuredValue: { ID: 1, type: enums1.DataType.UINT32 },
            maxMeasuredValue: { ID: 2, type: enums1.DataType.UINT32 },
            tolerance: { ID: 3, type: enums1.DataType.UINT8 },
        },
        commands: {},
        commandsResponse: {},
    },
};



Save the file
Restart Zigbee2MQTT


The device can now be connected to your Zigbee network and with this to your Home Assistant.




Directory structure


3d-print: All 3D print related files
cad: All relevant 3D models
docs: All kinds of project documentation like schematics, BOM, etc.


drawings: 2D drawings for subcomponents, etc.
images: All documentation related images

hardware: KiCad project for the PCB
firmware: Zephyr project for the device firmware
prebuilt: Prebuilt binaries
production: Production files from the latest CI/CD run
z2m: Zigbee2MQTT related files


Ressources


<![CDATA[]]>Adding new Zigbee2MQTT devices<![CDATA[]]>
<![CDATA[]]>Zigbee Cluster Library Specification<![CDATA[]]>
<![CDATA[]]>Generating HEX files for Zigbee production configuration<![CDATA[]]>
<![CDATA[]]>Zigbee Converters<![CDATA[]]>
<![CDATA[]]>KiBot Template<![CDATA[]]>


Maintainer


Daniel Kampert