background
Moon

Ambient Light Sensor

Hardware

There are 2 possible solutions, based on how much effort you're willing to put into the sensor and how much you care about the price and looks.


Solution 1: No-solder sensor

Characteristics

  1. Clean
  2. Easy to make
  3. Readily available parts
  4. Expensive
  5. A bit bulky

Components

Assembly

  1. Connect one end of the Stemma QT cable to the QT connector of the Metro ESP32-S2 board
  2. Connect the other end of the Stemma QT cable to any of the QT connectors of the TSL2591 sensor

no solder sensor metro esp32 s2 stemma qt tsl2591

Enter ROM Bootloader Mode

Entering the bootloader is easy. Complete the following steps.

  1. Make sure your ESP32-S2 is plugged into USB port to your computer using a data/sync cable. Charge-only cables will not work!
  2. Turn on the On/Off switch* - check that you see the OK light on so you know the board is powered, a prerequisite!
  3. Press and hold the DFU / Boot0 button down. Don't let go of it yet!
  4. Press and release the Reset button. You should have the DFU/Boot0 button pressed while you do this.
  5. Now you can release the DFU / Boot0 button
  6. Check your computer for a new serial port (on macOS it appears as a file beginning with /dev/cu.usb)
    • Run this in a terminal to list possible serial ports: ls -l /dev/cu.usb*

Now you can start firmware installation by following the steps here: Firmware Installation

Notes:


Solution 2: Solder or wire-through-hole

Characteristics

  1. Cheap
  2. Compact
  3. Not so clean looking
  4. Needs a bit more manual work
  5. Parts are not always in stock

Components

Assembly for ESP32 boards

  1. Connect one end of the Stemma QT cable to any of the QT connectors of the TSL2591 sensor
  2. Route the wires as the following:
    • Black wire to ground (the pin marked with G)
    • Red wire to 3 volts (the pin marked with 3V)
    • Blue wire to pin 19
    • Yellow wire to pin 23
  3. Connect the wires:
    1. If the board has holes (no pin headers soldered): Insert the male header of each wire into the pin hole and:
      • either solder the pin to the hole
      • ...or bend the pin around the hole so that it always makes contact with the metal around the hole and stays in place
    2. If the board has pin headers soldered: Insert each pin into the female header of each wire

solder sensor lolin32 stemma qt tsl2591 solder sensor nodemcu stemma qt tsl2591

Assembly for ESP8266 boards

  1. Connect one end of the Stemma QT cable to any of the QT connectors of the TSL2591 sensor
  2. Route the wires as the following:
    • Black wire to ground (the pin marked with GND )
    • Red wire to 3 volts (the pin marked with 3V3)
    • Blue wire to GPIO4 (the pin marked with D2 on NodeMCU and Wemos D1 Mini)
    • Yellow wire to GPIO5 (the pin marked with D1 on NodeMCU and Wemos D1 Mini)
  3. Connect the wires:
    1. If the board has holes (no pin headers soldered): Insert the male header of each wire into the pin hole and:
      • either solder the pin to the hole
      • ...or bend the pin around the hole so that it always makes contact with the metal around the hole and stays in place
    2. If the board has pin headers soldered: Insert each pin into the female header of each wire

solder sensor nodemcu esp8266 stemma qt tsl2591 solder sensor sparkfun thing esp8266 stemma qt tsl2591

Firmware

Lunar has an automated process for installing the firmware on ESP32/ESP8266 boards.

Click on Install firmware on Ambient Light Sensor in the Lunar menu to start the process: lunar menu bar icon lunar install firmware menu item

Parameters

A small window with firmware parameters will appear.

ambient light sensor firmware installer credentials

Installing

After clicking the Start button, Lunar will begin a three step process:

ambient light sensor firmware installing

Installation done

If the installation finished successfully, you will see a message as in the image below.

You can click on the Done button to close the window and let Lunar search for the sensor on the local network.

ambient light sensor firmware install done

Sensor Mode Detection

If the sensor booted into the new firmware and connected to the local network, you will notice that Lunar has made Sensor Mode available in the mode dropdown from the top-right part of the Lunar window.

You can click on it to activate it, or choose Auto Mode if you want Lunar to automatically fallback to other modes if the sensor becomes unavailable. sensor mode menu item

Lux value

When Sensor Mode is activated, you can also see the current ambient light around the sensor in the Lunar menu. lunar menu bar icon lunar menu lux

Troubleshooting

Error on flashing the firmware

If you get an error on the firmware installation process, you should see a View logs button. Click it to open the logs in a log viewer.

You can also view the logs manually by opening /tmp/lunar-sensor-install.log in any text editor.

If you don't understand the error from the logs, you can upload them on Lunar's Discord community and I'll take a look.

If you understand the error, you may try to tweak the firmware:


Lunar doesn't detect the sensor

First check if the sensor booted and connected to the local network: