Customizable Word Clock for Home Assistant / ESPHome

This word clock can be integrated into home assistant to not only display the time but also data from a variety of sensors (e.g. rubbish collection, weather, etc.)

• Different colours can be used for those to give an indication of the magnitude of a numeric sensor or one of several possible values for a text sensor

Time is automatically synchronized with the time of your home assistant instance and displayed to the minute:

• Via text in 5 minute granularity, i.e. o'clock, five past, ten past, quarter past, twenty past, twentyfive past, half past, twentyfive to, twenty to, quarter to, ten to, five to
• Four dots in the bottom row provide the for minute granularity, e.g. “ten past eleven” with 3 dots indicates 11:13

An OpenSCAD source file is provided so that the word and icon layout can very easily be adjusted, e.g. to use a different language or different icons.

If you have a well-calibrated printer, you can print it in such a way that the characters and icons are entirely invisible unless they're lit up.

It should also be possible to run it without home assistant, but you'll need to provide your own code in that case.

To replace the icons, just download the ones you want as svgs from https://pictogrammers.com/library/mdi/, place them in the same directory as the .scad file, and reference them from the file. Sizing and positioning should work out-of-the-box. You can add up to 6 icons, though it may look a little cramped with the minute display at the bottom, so 4 are recommended.

Required Additional Hardware

• WS2812 Addressable RGB LED strip with 60 LEDs / m. You'll need 121 LEDs, so just over 2m, though with a bit of extra soldering you can save a few LEDs (see Assembly Instructions)
• A microcontroller capable of running ESPHome (e.g. D1 mini)
• 4 of each M3 bolts, nuts, and washers. I've used 10mm bolts, but anything between ~8 and 16 should work fine.
• A sheet of tracing paper or similar to act as a diffuser
• Equipment for soldering
• One 40mm by 60mm perfboard. This is not strictly necessary, but without it, you'll need to modify the microcontroller mounting mechanism
• Optional: some JST connectors or similar (1 2-wire, 1 3-wire)
• If your printer cannot print perfect first layers, you may want to get some automotive tinting foil or similar in order to make the unlit letters less obvious
• Technically, the LED strip should be driven with 5V logic voltage. Many microcontrollers incl. the D1 mini have a logic voltage of 3.3V. 3.3V should typically be enough to be registered as high by the chips on the LEDs, but if it doesn't work, you could either try a different LED strip or include a logic level shifter in the circuit
• Not required but helpful tools for testing and calibration:
  • Multimeter
  • Breadboard

Filament Recommendations

The stencil that contains the letters should ideally use a filament that is not extremely opaque as you want the LEDs to shine through a single layer of black filament. Elegoo black PLA has worked very well for me and is very cheap.

Printing Instructions

• No supports are required for any part of the model
  • Some parts use sacrificial bridging layers that you can poke a nail through after printing
• Some parts have a brim integrated into the model. The brim is sized to fit on a bed with 210mm depth. If your bed is deeper, you can adjust printer_max_y to get a stronger brim
• First you'll want to print two test components to make sure that tolerances and first layer quality are adequate:
  • nut_test.stl is the housing for one of the M3 nuts. Slice it to insert a print pause just before the cutout for the nut gets filled and insert it. If there are issues with tolerances, adjust them in the OpenSCAD file and try again
  • stencil_test.stl is for testing the plate that the light will shine through to show the letters, specifically its first layer
    • The file has a first layer height of 0.15mm, so make sure to set that in your slicer
    • Print it, make sure it prints smoothely, and once it's down, check if the LEDs can shine through it sufficiently brightly
      • Keep in mind that you will likely not be able to run the LEDs at full brightness unless you power them separately from the microcontroller (see below for more details)
    • If the letters aren't bright enough, you can experiment with “stencil_first_layer_height” in the OpenSCAD file (remember to set the first layer height in the slicer accordingly) and/or the filament you're using.
    • Note, that if the see-through layer looks uneven, it is very unlikely that at the current calibration, your printer will be able to print the entire plate correctly. If you can't get the first layer good enough, you may need to consider setting the stencil_first_layer_height to 0, as well as replacing the font with one suitable for stencils (i.e. where there are no disconnected holes in the letters)
• All parts should be printed in the original orientation of the files
• The frame needs to be have a pause inserted in the slicer just before the slots for the nuts get covered, so that you can insert them during the print

ESPHome Configuration Instructions

• A yaml file as well as wordclock.h are provided, the latter should require no modification. Printables won't upload .yaml or .h files, so they have an additional .txt at the end that you'll have to remove.
• If you have a little bit of experience with ESPHome, modifying the code to display your own information should be relatively straightforward
  • In home assistant, you need to define some sensors to provide the information that should be displayed. Using template sensors to distill existing information down can be helpful. E.g. I have sensors in my home assistant that include pollen loads of different types of pollen, or hourly temperature forecasts, I use template sensors to create a weighted sum of pollen load based on how strongly I react to them, and to get the minimum temperature over the following 24h period
  • For numeric values, there are threshold values that determine at what values the colour changes (off → green → yellow → orange → red → purple)
  • For text sensors, you can create a map to associate values with colours
• If you modify the layout of the text in OpenSCAD, e.g. to change the language, you will need to adjust the mapping of words to indexes and lengths along the LED strip. Note, that every other line counts from right to left due to the way the LEDs will be connected

Assembly Instructions

Use the attached pictures to help guide you through these steps.

• Cut the LED strip into segments with 11 LEDs each and stick those into the groves on led_plate.stl
  • If you don't have enough for 121 LEDs you can leave out the LEDs for those letters in the matrix that are not parts of words or icons and instead bridge those segments with wires. This will require some adjustments of the offsets in the code though
• Solder on wires to connect the LED strip segments in a zig-zag starting at the top left and ending at the bottom right (i.e. the connections between the first and the second row will be on the right with the LEDs facing you,  the next one on the left, etc.)
• Solder on wires from the top left and bottom right that will later connect to your microcontroller. It will be easier to take everything apart later if you use JST connectors to connect these wires and the wires from the microcontroller, but you could also solder it directly (in that case you should leave the wires a bit longer for ease of installation)
  • 3 wires from the top, 2 from the bottom (i.e. skip the data line at the bottom)
    • Injecting power from both sides helps minimize voltage drop across the LED strip, but is not strictly required
  • Make sure to mark the wires so that you know which is which

Interlude - Brightness Calibration

Unless you are planning to power the LEDs with a separate power supply, you should limit the brightness of the LEDs to make sure you will never be drawing more than ~300-400mA from the 5V pin of the microcontroller (YMMV, consult spec sheets to be sure). With the provided configuration, at most ~30 LEDs will be lit at once, so you want to limit the current draw to ~10mA / LED

• Install ESPHome on the microcontroller using the attached yaml file. Make sure to upload wordlock.h to esphome/includes/
  • For the initial test, reduce the brightness in int brightness = 160; in the yaml file to a lower value, e.g. 50
• Use a breadboard to connect the wires coming from the LEDs to 5V, GND, and a data pin (I used D4, if you use a different one, make sure to adjust the code accordingly) on the microcontroller
  • Set it up so you can measure the current draw from the 5V port with your multimeter
• Power the microcontroller. Once it displays the time (assuming that everything works), make a note of the current draw from the 5V pin and divide it by the number of LEDs currently lit. You can then increase the brightness value and reinstall the sketch via ESPHome. Keep doing this until you have a good brightness without drawing too much current. 160 worked for me but YMMV depending on the LED strip you used.

Assembly Instructions - Continued

• Solder the microcontroller onto the perboard. If you use connectors, solder their wires onto the perfboard as well. You need 2 wires each for 5V and GND and one data wire.
• Carefully place the stencil into the frame. Make sure there are no sharp objects lying below the frame, the surface of the stencil can be somewhat fragile. The smooth side should face down, i.e. towards the outside
• Cut your diffuser to size, making sure to include the cutouts for the screw pillars and place it on top of the stencil
• Put the baffles on top
• If you're soldering the wires from the LED strip directly to the perf board, you should do that now, before you place the LED plate. If you use connectors, make sure all the soldering is done, but connecting can wait
• Put the LED plate on top of the baffles. With the frame upside down, the 3 wires should come out at the top right
• Clean out the sacrificial layers in the holes of the wall mount. Place the wallmount next to where the 3 wires come out and screw in using two M3 bolts and two washers
  • If the sacrificial layer just above the nut hasn't been thoroughly cleaned up, you may need some force to push the bolts through, but it should still work fine
• Take the two parts of the microcontroller holder (you may have to clean out the cutouts with a scalpel depending on how well the bridges printed), put the microcontroller in between, and screw it into the two holes as above
• If you use connectors for the wiring, you can connect them now
• You're done :-)