CircuitPython Powered Smart Alarm Clock

This Smart Alarm Clock is designed to be an intelligent timekeeper that responds to both light and motion. The display automatically turns off in darkness and turns on when the room is bright. If the room is dark, simply shake the alarm clock to briefly show the time for 5 seconds.

Powered by CircuitPython on an Adafruit Matrix Portal M4, this project combines a light sensor, an accelerometer, and an RGB matrix display to create a customizable, interactive clock. It also features Wi-Fi-enabled time synchronization and displays real-time weather updates when it turns on in the morning. In this guide, I’ll walk you through how I built it, including hardware setup, CircuitPython coding, and making everything work seamlessly. Let’s get started!

@tommykoster.bsky.social

Special thanks to John Park from Adafruit for creating his clock and weather matrix portal display. This project uses a lot of code that he created. Links to the projects are below:

1. https://learn.adafruit.com/network-connected-metro-rgb-matrix-clock/code-the-matrix-clock
2. https://learn.adafruit.com/weather-display-matrix/code-the-weather-display-matrix

Materials List:

1. Matrix Portal M4: https://www.adafruit.com/product/4745
2. 64 x 32 RGB LED Matrix: https://www.adafruit.com/product/2278
3. Adafruit VCNL4040 Light and Proximity Sensor: https://www.adafruit.com/product/4161
4. Stemma QT 4-Pin Cable: https://www.adafruit.com/product/4210
5. USB C Cable

Firstly you are going to have to setup your matrix portal with the newest version of circuit python. The download link for this can be found here:

This is the same process for all circuitpython boards if you have worked with circuitpython before. You will need to plug the board into your computer using usb type c.

Here's a good tutorial on how to do it if for the matrix portal if you have never done it before:

Here is the download link for the newest version of circuitpython for the matrix portal m4:

1. https://circuitpython.org/board/matrixportal_m4/

Now, make sure the board is plugged into your computer. Replace all the data in circuitpy with the data from the following GitHub repository:

https://github.com/koster51/SmartAlarmClock/tree/main

Next you need to setup your secrets.py folder to so that your alarm clock can connect to wifi, get time, and use the weather api.

Double click secrets.py and you should see something like this:

secrets = {

'ssid' : '',

'password' : '',

'aio_username' : "",

'aio_key' : '',

'openweather_token':'',

'location' : 'New York, US'

}

1. Set ssid equal to the name of your wifi network
2. Set password to your wifi network's password
3. Go to https://io.adafruit.com/ and creat an account
4. Once you have created an account go to "overview" and click on the key icon. This will give you the username and password that you will fill into 'aio_username' and 'aio_key'.
5. Sign up for an account at https://openweathermap.org.
6. Click on your account and grab an api key. Copy this into 'openweather_token'. This is how your alarm clock will access the weather every morning
7. Fill in your location under 'location'. Make sure it is in the same format as the example above.

Now we are going to go into the main section of the code and talk about different settings you can manipulate in the alarm clock. You can open this code and your favorite circuit python code editor (probably MU or PyCharm)

This code controls specific aspects of the alarm.

1. Blink changes weather the colon blinks or not.
2. Units can be changed to "metric" if you do not like imperial.
3. Weather time display changes how long the weather api is displayed before switching back to being a clock.
4. font is connected to my preferred font file, but you can upload any bitmap font you want that is around 12 x 24 and it should work
5. light_sensor_threshold is how dark the room must be for the light to turn off
6. shaker_threshold is how hard you must shake to change turn the clock back on

Also make sure to change tz_offset here to be correct for your time zone. This is currently set up to work on the east coast of the United States.

After you have coded the board we can now plug everything in

1. Start by screwing the red and black wires into the terminals on the matrix m4 portal. Make sure red is connected to the '5v' option and black is connected to 'gnd'
2. Next plug the VCNL4040 sensor into the board using the Stemma QT cable. The port on the matrix portal m4 is located in the bottom left as shown by the second photo, and on the VCNL4040 it is located on either side, but you should use the left side
3. After that plug the board into the led matrix. If you want to plug it straight into the matrix it is going to stick out a little on the outside. THIS WILL NOT WORK IF YOU PLUG IT IN ON THE WRONG SIDE OR BACKWARDS SO BE CAREFUL. I didn't want to have my board sticking out so I used jumper cables to connect the board to the provided wire, then the provided wire to the board. (I am sure there is a better way of doing this but I was in a time crunch and this was the best way that I could figure out)
4. Now plug your board in.

At this point all the electronics should be working. If you cover the light sensor the display should turn off. If you shake the matrix portal while the display is off then the display should turn back on for 5 seconds. And if you take your hand off the light sensor then the display should turn back on and show you the weather for a couple seconds before shifting back to being a clock.

Depending on how large you want your box to be / the size of your matrix portal the exact dimensions of your box will vary. I'll walk you through a general process for creating a laser cut box that will house your smart alarm clock.

Firstly, I went to https://en.makercase.com/#/basicbox and made a box. Here is how I did the calculations for the dimensions.

1. Start off with the thickness of the wood you are laser cutting. We will say this is equal to x. Then we will call the dimensions of your display h for height, w for width, and t for thickness.
2. Set the inside dimension of you box from maker case equal to (h + 4x + 0.1) x (w +4x+0.1) x (whatever depth you chose for your alarm clock, I did 6 inches just so I had a ton of space for all the components)
3. Move this svg file to adobe illustrator and on one of the front panels draw a hole that is the height and width of your display. draw a hole on the opposite panel that can fit your cable and draw a hole on top for the sensor that is 1 inch by 3/4 inches.
4. Next create 6 rectangles that are t x l
5. Then create 4 rectangles that are t x (h-2x)
6. Box in the laser cutter
7. Now create a separate file (this will be to cut the acrylic covers for the display and sensor). Create two rectangles one should be 1.2 inches by 1 inch and the other should be (h + 4x + ) x (w +4x+) inches

Next you need to assemble the box

1. Assemble the outside pieces (remember to leave a side open)
2. Slide the large acrylic piece in
3. Support the acryllic piece using the rectangles of wood
4. Place display in
5. Support the display with the rectangular pieces of wood
6. Wire everything together
7. Tape the sensor to the top cutout of the box.

And Done! I have attached a photo of what the inside of my box looks like, yours should look somewhat similar.

Now you should be able to plug in your box and everything should be working.