GurgleApps Word Clock Assembly With an Ambient Light Sensor

The GurlgeApps Word Clock is a USB-powered open-source digital clock which shows the time as words in English. The letters in an 8x8 grid layout can be individually illuminated in any colour. This small desktop clock is a descendant of the multi-language Biegert & Funk QLOCKTWO clocks which use larger 10x11 grids. These clocks tell the time to the nearest five minutes.

The 3D printed clock is a kit based on the Raspberry Pi Pico W. The clock connects to the Internet over Wi-Fi to retrieve the time using the Network Time Protocol (NTP). The software is written in MicroPython making it easy to modify. The clock can be purchased pre-assembled.

This article describes:

1. the assembly of the clock together with some analysis of how it works;
2. the addition of a simple light sensor to measure ambient light and automatically control display brightness;
3. some new background modes for the displayed time;
4. a brief look at the "WS2812B" protocol for the RGB LEDs.

The kit was purchased in October 2025 and was supplied with the new, custom 8x8 RGB LED matrix. This can be seen in Instructables: Testing an RGB LED Matrix With Different Supply Voltages.

The kit involves some very simple soldering. After tackling a simple learning-to-solder kit it would make a great second soldering project.

1. GurgleApps Word Clock : Etsy (select Full Kit, also sold as components if you wish to 3D print parts yourself)
2. Soldering iron and solder.
3. A small pair of pliers is useful to help snap-off the superfluous parts of the RGB LED panel.
4. Optional: hot glue gun (to better hold the Pi Pico W in place).
5. Ambient light sensing
6. A small phototransistor around 3mm diameter, e.g. LTR-4206: Kitronik
7. 10k resistor.
8. Heatshrink and something to shrink it.
9. Three wires.
10. Glue (optional).
11. A craft knife, very small files and 1mm-1.5mm drill bit can be useful if any of the 3d printed parts need cleaning up.

The clock is constructed from (in order from front to back):

1. a face plate made from a PCB with a translucent substrate,
2. a plastic spacer frame which surrounds the 8x8 RGB LED matrix;
3. another plastic spacer frame (middle layer shown above in orange but with wrong orientation, needs to be turned upside down) with supports to hold the RGB LED matrix against the face plate and hold the Pi Pico W in place;
4. a plastic back plate with supports for the Pi Pico W and a tiny flexible area above the Pi Pico W's BOOTSEL button to allow the button to be pressed when encased;
5. two plastic angled legs.

These are held together with four silver or black bolts. Two more bolts are supplied which can be used to locate the RGB LED matrix in place. The frame does a good job of holding it making these optional. The plastic parts are 3D printed.

The 8x8 size of matrix is useful for being able to use readily available commercial RGB LED matrixes like the one shown in the old photograph above. The clock now comes with a custom one with same dimensions.

The RGB LED matrix uses the WS2812B interface - people often call these NeoPixels after Adafruit's brand name. It is intended to be powered from the 3V3(OUT) pin on the Pi Pico W. This type of RGB Matrix would normally be powered at 5V using the VBUS pin. The lower voltage works well and has the useful side-effect of lowering the current even if many LEDs are illuminated brightly.

The datasheet description follows.

3V3 is the main 3.3V supply to RP2040 and its I/O, generated by the on-board SMPS. This pin can be used to power external circuitry (maximum output current will depend on RP2040 load and VSYS voltage; it is recommended to keep the load on this pin under 300mA)

That recommendation is unchanged for the RP2350-based Pi Pico 2 W.

The software is written in MicroPython using the asyncio library and a web server library. It consists of the following files:

1. several MicroPython files,
2. some html and javascript files for the web server root directory and
3. a config.json file (several template files are provided).

The software connects to Wi-Fi to retrieve the time using the network time protocol (NTP) from servers on the Internet and then periodically polls these to keep good time. An http (not https) web server allows the status of the clock to be checked and the settings can be inspected and changed. There's a lot of code dedicated to keeping the Wi-Fi connection up and retrying NTP requests but if the clock cannot connect to Wi-Fi then it starts up as an access point using the fixed SSID gurgleapps and password gurgleapps.

At startup the software

1. displays some attractive patterns,
2. does a test of all red, green and blue on the RGB LEDs and
3. shows the IP address twice assuming the Wi-Fi (and DHCP) works.

The clock will then run in the chosen display mode. This article shows the software addition of some background modes.

The software has support for some alternative single colour LED displays using the HT16K33 and MAX7219 drivers.

The software should run on other MicroPython capable boards which have similar resources (memory and file system space) to a Pi Pico W.

The config.json file is both read and written to by the software. This file contains the Wi-Fi password - take care not to put this in a public place.

The additional of a light sensor is fairly straightforward, the steps are listed below.

1. Make a suitable hole in the 4mm top edge of the back plate of the case away from where the wires run from the RGB LED matrix. This can easily be done with a small file. The LTR-4206 phototransistor is 3mm across (flange is 4mm). Making a hole slightly larger than this to allow for heatshrink works well. The hole can be snug enough to hold the phototransistor with the heatshrink wrapping and not need gluing. Making the hole slightly wider at the outside section will provide a wider angle of incident light measurement.
2. Solder the phototransistor to the 10k resistor which forms the other half of the potential divider. The phototransistor's collector which is indicated by a flat side and a short lead needs to be connected to the red wire.
3. Connect the light sensor wires to the Pi Pico W:
4. red to 3V3,
5. white to GP26 (this is an analogue capable pin),
6. black to AGND (pin 33) or any convenient GND.

In general, it's always worth doing an inventory check before starting any construction process.

The assembly is described in DIY WiFi-Controlled Word Clock Kit Assembly Guide which includes a video. The top and bottom bars on the new custom RGB LED matrix need to be removed by snapping them off - a pair of pliers is useful for this as shown at 01:46 in the video UPDATE - We Made A Custom RGB LED Matrix Display!

There are three wires which need to be soldered at both ends. The video provides some wise advice to leave these a little longer than required. These are best left untinned to make them easier to pass through the Pi Pico W's small holes for soldering. Some care needs to be taken inserting them into the holes to avoid stray strands shorting to adjacent pads. The wires can also be soldered flat onto the pads. The black wire tends to run across one of the RGB LED registration holes if it's soldered in a typical orientation - soldering with the wire at an angle will avoid blocking the hole as shown in the "Plan B" photographs.

The RGB LED matrix's red wire is intended to be connected to the 3V3(OUT) pin on the Pi Pico W. For this assembly it was soldered to the VBUS pin which provides 5V direct from the USB connector. The underside of the VBUS pin presses against the plastic case. The wire was soldered just to the top-side only of the pad taking care not to foul the nearby support position/hole. This will make the letters brighter than they normally are and will increase the current drawn at equivalent software brightness settings. The pros and cons of this change are discussed in more detail later in the article.

The plastic case has four small nubs to hold the Pi Pico W board in place. The instructions recommend use of a hot glue gun to improve the secureness of the board.

The plastic components are 3D printed. It's worth checking the parts are printed cleanly. A sharp knife and needle file (or nail file) may be useful to clean up any chaff. A tiny drill bit can be used to align and clean up the screw holes.

If the case is aligned and the holes are clean then the bolts will pass through them and the nuts can be tightened on the back. The bolts can be turned if you have a small allen key.

The software installation process using Thonny is described in Software Setup: Configuring Your Wifi Word Clock. There are three choices here:

1. the v1.0.0 release in a zip file (the instructions mention this one),
2. the files from the main branch - tested and this works,
3. the forked (from main) version used in this article with extra features.

The config.json file needs to be created and have the Wi-Fi SSID and password added to it. The config_wifi.json is a useful template file to start with, it's shown below, the ENABLE_WS2812B is for the RGB LED matrix display.

As can be seen, this file contains the Wi-Fi password - take care not to put this file in a public place.

If you have added a light sensor then you'll need this in the configuration to use GP26. At the moment this makes the clock switch to adaptive brightness mode automatically.

For summer time in the United Kingdom you need to add an offset in seconds to deal with Daylight Savings Time. If you live in New York then this would be -14400 in summer and -18000 for the rest of the year.

This value can also be more easily set by using the web interface to set a time - under the covers a new TIME_OFFSET is calculated and saved. At the moment this features always sets the seconds to 0, to make it accurate set the value about a second or two before the set time is reached.

MicroPython v1.26.1 was used for this article.

The software for the Word Clock supports different modes for displaying the words. The modes with names from the web interface are described below.

1. Single Colour - a single colour which can be set from a palette.
2. Rainbow - colours from a (HSV) colour wheel graduated across the words.
3. Word Colours - three colours which can be set for each part of the spelled out time.
4. Random - random colours for each letter updated every 10 seconds.

A background should really be applicable to all of those display modes and not just linked with one. A new class was developed called MatrixBackground to provide a blank background to replicate the current behaviour and act as a parent class for some more interesting backgrounds.

1. Blank - replicates original code.
2. Digital Rain - randomly falling green "rain drops" with a trail.
3. Minutes Offset - the minutes are shown as an offset from the time in words, the offset of -2, -1, 1 or 2 is represented as a vertical bar positioned from left to right.
4. Minutes Digit - the final digit of the time is displayed, when this changes on the minute it is scrolled off the screen slowly and the new digit appears.

The code normally updates the display approximately every 10 seconds. MatrixBackground has a feature to designate an update_rate which modifies the frequency of this loop. It's set to 15 (updates per second) for Digital Rain, 1 for Minutes backgrounds and 0 for Blank to use original update frequency.

The photographs above are (in order left to right):

1. Single Colour on Digital Rain (at high brightness),
2. Random on Minutes Offset (showing 10:51) and
3. Single Colour on Minutes Digit (showing 12:22).

The video above shows the start-up sequence which features some attractive patterns, a test of red, green and blue on the RGB LEDs and shows the IP address twice after the Pi Pico W has connected to the Wi-Fi. The clock then shows the time as "TWENTY PAST ELEVEN" in Single Colour mode with the Digital Rain background. The time is presented rounded to the nearest five minutes, the time could be anywhere between 11:18 and 11:22. A torch illuminates the light sensor to show how the brightness level automatically and slowly adapts to ambient level.

The video above shows the Single Colour display mode and the Minutes Digit background. The time changes from "TEN PAST TWELVE" with a 2 in the background representing 12:12 to "FIFTEEN PAST TWELVE" with a 3 in the background representing 12:23 by scrolling the background digit off and on the screen.

The ScanaStudio screenshot above shows the capture from an Ikalogic SQ25 logic analyser. The data is from the signal pin used to transmit an update to the first row of the custom RGB LED matrix. It's running at 25Msps sample rate (40 nanosecond resolution) - this isn't ideal to look at the timing for this fast protocol but it's the maximum rate on this low-end analyser. The first byte is shown which is the green data (0x55) for the first RGB LED. The image has been manually annotated with the high,low pulse widths as the font in ScanaStudio is very small for this. These are supposed to be either 400,850 or 800,450.

Protocol

The protocol for strips of this type of one-wire addressable RGB LEDs sends data in a burst of pulses. A matrix is wired as a single strip typically with the end RGB LED of each row connected to the first one on the next row. The data is sent in green/red/blue order bytes (this order can vary) with the most significant bit of each byte first. For each transmission to update the RGB LEDs there's a minimum period where the signal needs to be low called the reset period. After that the data is sent with the pulse width of an 800kHz square wave varied to varied to indicate a 0 or 1. Unfortunately there is no standard for this protocol and manufacturers have different timing specifications even for their own types over time. Three datasheet examples are shown above.

The custom RGB LED matrix didn't initially work when tested with a Pi Pico 2 W. The first pixel might work but the other 63 would typically be very bright white causing a huge current draw.

The first (incorrect) guess was that heat from repeated soldering to the three pads had damaged the RGB LED on the opposite side of the board. As this is the first one it has to pass on the signal to subsequent ones making damage here very problematic.

A replacement RGB LED matrix board was purchased and this exhibited a near-identical problem. After some thought and a bit of research it turned out to be a problem that had perplexed other people too. A quick REPL test showed that changing the CPU frequency from the Pi Pico 2 W default 150MHz to 160MHz made it work. This warranted further investigation.

Pi Pico 2 W Testing

The MicroPython neopixel library has a very useful feature to be able to specify the pulse widths (duration in nanoseconds). This is the preferred way of exploring and accommodating any RGB LEDs with different timing requirements.

The small neopixel-timing.py program was used to test various combinations including some custom timing using a pulse 50ns shorter than normal for the 0 value. The pass/fail result was determined by watching the RGB LEDs for a few minutes to ensure they were visually correct.

1. Test 1 default timing at clock 125MHz: fail
2. Test 2 custom timing at clock 125MHz: pass
3. Test 3 default timing at clock 150MHz: fail
4. Test 4 custom timing at clock 150MHz: pass
5. Test 5 default timing at clock 160MHz: pass
6. Test 6 custom timing at clock 160MHz: pass

The default timing in nanoseconds is [400, 850, 800, 450], the custom timing used here to investigate this issue is [350, 900, 800, 450]. The protocol timing must be extremely close to the practical boundary for this type of RGB LED.

The MicroPython implementation for the RP2040 and RP2350 microcontrollers has approximate timing for these very short duration pulses. The final bit of the byte suffers from additional delay/duration. The issue is discussed in more detail in GitHub: micropython / micropython: neopixel protocol timings depart from set values on Pi Pico 2 W causing failures #18295.

Workaround/Fix

Two values were tested in the Word Clock software and appeared to work okay with the combination of Pi Pico 2 W and custom RGB LED matrix.

1. 100ns shorter bit 0 pulse: timing=(300, 950, 800, 450).
2. CircuitPython's current library values: timing=(300, 900, 700, 500) **.

Other microcontroller and RGB LED matrix hardware combinations need to be thoroughly tested to add more weight to these numbers being viable for this clock.

** These add up to 1200ns rather than the expected 1250ns for an 800kHz pulse train, this is intentional.

A conservative benchmark based on testing would be 18mA per full white rightness RGB LED powered from 3V3(OUT) and 40mA powered from VBUS. With a 250mA and 850mA budget this is only 14 and 21 illuminated letters at once at full brightness.

A brightness level of (246.5 - 25.4) / (516.2 - 45.0) * 255 = 120 at 5.0V would be equivalent to 255 at 3.3V.

The code at the moment supports brightness levels of 0 to 15 intended for use at 3.3V. A brightness range of 0 to 10 keeps the current capped at a similar level. The code could be enhanced to apply a brightness limit based on the RGB LED supply voltages specified by configuration.

3.3V from 3V3(OUT)

1. This is the output from the simple, small switch-mode power supply on the Pi Pico W board.
2. Pi Pico W recommends 300mA maximum from this pin (same for Pi Pico 2 W).
3. These type of RGB LEDs typically have a lowest voltage specified as 3.5V or 3.7V but empirically these do work at 3.3V. A test of this board shows they have a consistent white output to the eye from 3.0V to 5.0V. The driver chip continues to work even at 1.9V where only the red LED barely functions!
4. The signal high voltage matches the supply voltage.
5. This pad is easily accessible in Word Clock case.
6. With a reasonable power supply tests show the RGB LED matrix at 3.18V with all illuminated at (255, 255, 255) draw 923mA. Using 13 pixels as a benchmark the current per pixel at 3.3V is (246.5 - 25.4) / 13 = 17mA.
7. Using this pin presents a risk of exceeding the maximum permissible current and stressing the switch-mode power supply components.

5.0V from VBUS

1. This is a direct connection to the USB power.
2. Micro-B USB from a desktop PC might be capable of 1.5A, probably more from a power bank. These are high currents to put through the Pi Pico W board.
3. 5.0V is the recommended voltage for these RGB LEDs.
4. The signal high voltage (Pi Pico W GPIO will be around 3.3V) is below the supply voltage. This isn't recommended but it works and is above the supply midpoint voltage (5/2 = 2.5V).
5. This pad can only be used from the top side of the Pi Pico W in the Word Clock case and cable needs careful routing to avoid the area around the hole which is used for a mounting/support point.
6. With a reasonable power supply tests show the RGB LED matrix at 4.64V with all illuminated at (255, 255, 255) draws 2.31A (power from a desktop/laptop will tend to limit this to 900mA or 1.5A). Using 13 pixels as a benchmark the current per pixel is (516.2 - 45.0) / 13 = 36mA.
7. Using this pin presents a risk of drawing very high currents with associated heating effects.

It's important to note that the software might not be intended to set lots of RGB LEDs to bright values but this could happen due to lack of awareness of this limitation or a bug.

Instructables: Testing an RGB LED Matrix With Different Supply Voltages shows a practical test of the RGB LED matrix.

The clock was left for 20 minutes each time in a dark room and with an LED torch (i.e. a cold light) illuminating the light sensor to check the temperature increase of the CPU. The Pi Pico's CPU temperature isn't calibrated but the relative difference is a useful gauge of any heating from the RGB LED matrix. The RGB LED matrix was powered by VBUS, the current was measured by an inexpensive USB power meter, the CPU temperature in Celsius was retrieved from the web interface.

1. Minimum brightness: desk temperature 24.6, CPU 29.86, current 0.07A.
2. Maximum brightness: desk temperature 24.4, CPU 33.60, current 0.22A.

Apart from the temperature at the desk the clock was resting on the numbers here aren't going to be very accurate. However, they do give a useful indication that the temperature rise is only 4 degrees Celsius, far from concerning. The faceplate feels slightly warm with normal clock display at maximum brightness.

The two images above are the top and bottom half of the original web interface**. The CPU Temp for the first reading can be seen.

** The background mode was added to this web page after this temperature check was performed.

The photograph above is the rust version of the QLOCKTWO Earth 45.

Some ideas to explore:

1. Add your own display mode or background mode.
2. Add software-based current limiting by capping brightness or the summed brightness of RGB LEDs based on a new configuration parameter which indicates the voltage. A limit of 250mA for 3.3V from 3V3(OUT) and 850mA for 5.0V from VBUS would be reasonable starting point.
3. Cautious addition of a loudspeaker.
4. Placement could be tricky as there's not much space inside. Either holes needs to be made to transmit sound and/or the speaker needs to be bonded to the rear panel or mounted on the outside.
5. Even small loudspeakers will require a transistor to deal with the current.
6. A piezo electric device might be suitable to drive directly from GPIO but the current would need to be measured to ensure its within the GPIO limit (RP2040 microcontroller datasheet states a 12mA maximum per GPIO) and if the volume is useful at this low current.
7. If there's room inside and the Pi Pico W doesn't get in the way try adding some downward facing LEDs to illuminate your desk.
8. Some small though-hole LEDs facing downward with suitable holes in the case could work. These should have current limiting resistors to keep them below 12mA if powered directly from GPIO and total current should not exceed 50mA.
9. Adafruit Sequins (green run at 7.5mA from Pi Pico W GPIO) might be more practical as these could be glued to the base with just the wires going through the case.
10. Flexible LED filaments might be viable too but would need extra components to vary brightness.
11. Make some ventilation holes in the case top and bottom to allow convective cooling beyond that from the narrow gaps between layers. Check before and after CPU temperature to see if this makes any difference when using the display at maximum brightness with bright backgrounds.
12. Investigate better approaches for handling time zones and daylight savings time. MicroPython does not have local time zone support, this is a challenging feature to provide locally on a microcontroller. A service on the Internet is one option to help with this.
13. Investigate using Wi-Fi signal strength variation to see if it's viable to detect the presence of people - people are very good at absorbing the gigahertz frequencies that Wi-Fi uses.

Some GurgleApps Word Clock hardware and software modifications:

1. Lori Pfahler: Pico W Episode 26: Word Clock Part 1 & Part 2 (YouTube) - a case variant to allow female headers on Pi Pico W to be externally accessible, this facilitates the use of a small breadboard on the back of the case.
2. Simon Walters: New inline method of indicating minutes on ‪@GurgleApps‬ Word Clock (YouTube)
3. More in Community Innovations section of GurgleApps Color WiFi Word Clock Kit.

Some other interesting clocks:

1. Word clocks
2. QLOCKTWO - the designer clock that started it all.
3. Instructables: Wordclock
4. Brett Oliver's Arduino Word Clock project & Arduino Word Clock Mini
5. Mark Sidell's Word Clock
6. Florian Klien: Making a Wordclock with Python - Talk at Grazer Linuxtage 2018 (YouTube)
7. Hackaday.IO: Small Word Clock by sjm4306
8. TechKiwiGadgets: Personalised Word Clock Kit
9. Adafruit Learn: Simple Vertical Wordclock
10. Hackster.io: Flip Dot Clock
11. Instructables: Make an Art Deco Clock With Temperature Module
12. Adafruit Learn: Network Connected RGB Matrix Clock
13. Bad Dog Designs Nixie Clocks
14. Instructables: Paper Sundial Kits

Other products/projects taking advantage of a translucent/transparent PCB substrate:

1. Blinkyparts
2. Rainbow Unicorn - Simple kit for a fantastic badge
3. Dino - From a time long gone, this soldering kit glows in all the colours of the rainbow
4. EDISON SCIENCE CORNER: Lets Make Transparent PCBs - Future of PCBs - the design of a (flexible) transparent PCB, possibly as part of an undeclared JLPCB promotion.

Further reading:

1. Instructables: Testing an RGB LED Matrix With Different Supply Voltages - testing the custom RGB LED matrix from the Word Clock kit at 2.7V to 5.0V.
2. Instructables: Powering Peripherals From a Microcontroller - Arduino UNO R3, Pi Pico W, Adafruit Feather NRF52840, BBC Micro:bit and Cytron Maker Nano RP2040 - the theory.
3. Instructables: Measuring Peripheral Power With Arduino UNO R3 and R4 WiFi, Pi Pico W, Adafruit Feather NRF52840, BBC Micro:bit V1 and V2, Cytron Maker Nano RP2040 - the practical.
4. Andreas Spiess: Precise Time without Internet: NTP Server from GPS Satellites (YouTube) - a Swiss homage to Time Nuts, a practical look at using the Raspberry Pi with inexpensive GPS modules to provide an accurate "local" time source which can be distributed using the Network Time Protocol (NTP).
5. The quest for the one true set of timings for the WS2812B/SK6812 (NeoPixel) protocol
6. GitHub: micropython / micropython: neopixel protocol timings depart from set values on Pi Pico 2 W causing failures #18295
7. GitHub: adafruit / circuitpython: test and adjust NeoPixel timings on multiple ports #6312
8. GitHub: adafruit / Adafruit_NeoPixel: WS2812B-Mini-V3/W timing issue #445
9. GitHub: gurgleapps / Gurgle-Apps-Word-Clock : Accommodate old and new RGB LED matrixes and Pi Pico 2 W #7