First, make sure you've loaded the latest Raspbian Lite operating system on your Raspberry Pi.  You can find the OS image download here, instructions for burning to an SD card image here, and a convenient guide here that explains how to load an operating system.

Next, have your Raspberry Pi connected to the Internet, either with a wired connection to its ethernet port, or by setting up wireless access to a WiFi network.  Check out the guide on network setup for more details on using wireless and WiFi networks with the Pi.

Once your Raspberry Pi is powered up and connected to a network you can follow the steps below to install the bedclock software.

If you're familiar with connecting to the Raspberry Pi over SSH you can use an SSH terminal application to connect.  If you aren't familiar with SSH, you can use the Adafruit Pi Finder tool to find your Raspberry Pi and open a terminal to run the installation. In either way, you should be able to be logged into the RPI as user pi.

Note with the latest versions of Raspbian (Jessie full & lite since ~February 2017) they disable SSH by default! Read below to see how to enable SSH so you can access the Pi with tools like Pi Finder.

Customization Options

As part of the Raspbian installation, visit the various options available and see if any of them needs tweaking. Setting the timezone is a good candidate. :)

Enable I2C via raspi-config

In order to read the gesture sensor, I2C must be enabled via the raspi-config interface. Follow the guide below for a step by step guide. If your familiar with this, use sudo raspi-config and enable I2C through the “Interfacing Options.”

Download: file
sudo raspi-config
  • Localization Options -> change timezone
  • Interfacing Options -> enable ssh
  • Interfacing Options -> enable I2C
Download: file
sudo apt-get install -y python-smbus i2c-tools

# Ensure i2c device is present
ls /dev/i2c*  && echo ok || echo bad error cannot see i2c

Install Matrix Driver

OK, now you are ready to install the driver for the LED matrix. We have a script that downloads the code and any prerequisite software. It works with the current Raspbian “Stretch” operating system (either the Lite or Desktop version). Walk through the options it presents and select the ones that pertain to your setup. If you get stuck, we have a more details in the Bonnet Matrix guide.

Download: file
curl >
sudo bash

The script will confirm your selections and offer one more chance to cancel without changes.

There’s a lot of software to update, download and install, so it may take up to 15 minutes or so to complete. Afterward, you’ll be asked whether you want to reboot the system.

Testing the Matrix Code

After the reboot, it's time to try the display! Run the following command and make sure it is working properly. By the way, it is okay to do this after the whole assembly; just come back here once the display is properly powered and connected.

Download: file
cd ~/rpi-rgb-led-matrix/examples-api-use

TIMEOUT='-t 10'
for X in 0 {3..11} ; do \
     PARAMS='--led-rows=64 --led-cols=64 --led-brightness=88'
     sudo ./demo ${PARAMS} ${TIMEOUT} --led-pixel-mapper="Rotate:${ROTATE}" -D${X}
     sleep 0.3

Press Control+C to stop the program and get back to the command line.

Install Git, Pip and Clone

Let's get the git command so we can clone the bedclock software repository. We will also need some Python packages, which we can easily obtain by using the pip command

Download: file
sudo apt-get install -y python3-pip git

cd && \
git clone -b ${BRANCH} \  bedclock.git

cd ~/bedclock.git && sudo -H pip3 install --upgrade -r ./requirements.txt

Automatic Startup

We will use systemd to start the program automatically. This is just a copy command away from the cloned repo.

Download: file
# add bedclock service to systemd
sudo cp -v ~/bedclock.git/bedclock/bin/bedclock.service \
sudo systemctl enable bedclock.service

# start the application
sudo systemctl start bedclock.service

You can monitor what is happening with the app by looking at the log or systemd status:

Download: file
sudo systemctl status bedclock.service

tail -F ~/bedclock.git/syslog.log | grep bedclock

Customize tweaks

There are lots of knobs that can be tweaked to make the clock behave as you want. Most of these settings are located in the file called After making the changes, make sure to restart the application by typing the following command

Download: file
sudo systemctl restart bedclock.service

If you want to start it manually, use

Download: file
sudo systemctl stop bedclock.service

Just like the time you ran the matrix demo, press the Control-C keys to stop the program and get back to the command line.


If you have an MQTT broker that your bedclock can talk to, you can enable it via the mqtt_enabled setting in the file.

That file will be located under the following directory:

# Edit file and modify the following parmameters:
# mqtt_broker_ip =
# mqtt_enabled = True
/bin/nano  ~/bedclock.git/bedclock/

Receiving events published by the bedclock application

Download: file
# Install mqtt client to poke bedclock via mqtt broker
$ sudo apt-get install -y mosquitto-clients

$ mosquitto_sub -v -h ${MQTT_BROKER} -t "/bedclock/motion" -t "/bedclock/light"
/bedclock/motion on
/bedclock/motion off
/bedclock/light 365

Configuring the clock to stay awake in the dark

If you don't want the clock to go blank when the room is dark, you can change its default behavior in by setting scr_stayOnInDarkRoomDefault = True. Or via MQTT, as shown below:

Download: file
$ mosquitto_pub -h ${MQTT_BROKER} -t /bedclock/stay -r -m "on"
$ mosquitto_pub -h ${MQTT_BROKER} -t /bedclock/stay -r -m "off"

# to clear topic from broker and use const.scr_stayOnInDarkRoomDefault
$ mosquitto_pub -h ${MQTT_BROKER} -t /bedclock/stay -r -n

Remove/disable unnecessary services

RPI Zero W handles the display just fine but it does not hurt to help it out by disabling unused things that compete for cycles. These were the ones I did on my setup, based on Henner's advice:

Download: file
sudo systemctl disable avahi-daemon && \
sudo systemctl stop avahi-daemon && \
sudo apt-get remove -y bluez bluez-firmware pi-bluetooth triggerhappy && \
echo ok

Safely Shutdown setup

Abruptly cutting power to the Pi can cause the files in the SD card to become corrupt. So, we suggest safely shutting down the Pi. There is a dedicated guide for enabling Read-Only mode, which will allow you to quickly turn off the Pi without risking corrupting the SD card.

This guide was first published on Dec 30, 2018. It was last updated on Dec 30, 2018.
This page (Coding) was last updated on Aug 07, 2020.