Setting up the Raspberry Pi

The normal operation of this project Is that your Raspberry Pi Zero W will be operated "headless" which means that it will only be operated remotely over your Wi-Fi network without a monitor, mouse, or keyboard. 

As mentioned previously you will need a PC that has an SD card reader so that you can download the software and install it to the card. Insert the SD card into the card reader on your PC.

Installing NOOBS

We will be using a system called NOOBS which is an easy way to prepare an SD card with an operating system for a Raspberry Pi.

Go to the Raspberry Pi software download page here:

Download the appropriate installer for your computer whether it be Windows, Mac, or Ubuntu for x86. When you run the imager program you will see this screen.

Click on the left-hand button of the imager program to choose your operating system. But before choosing which operating system to install, press CTRL + SHIFT + X

You will see a screen that looks like this

The overscan option doesn't apply because we won't be using a monitor. You can optionally create your own hostname which will be handy if you're going to create more than one of these devices or you have other Raspberry Pi devices on your Wi-Fi network. You should check "Enable SSH" and choose a password as shown above.

Then scroll down to the next section to set up your Wi-Fi SSID and password. Set your country ID. NOTE we do not recommend checking the "Allow public-key authentication" option at the top because honestly, we don't know what that means :-) We got by without it.

Scroll down further and optionally set the locale and keyboard layout. We suggest you skip the first run wizard. The other persistent settings you can leave or change according to your own wishes. When done, click on the SAVE button

Now select the top option "Raspberry Pi OS (32-bit)" then on the next screen click the middle button to choose the drive on your PC where the SD card is located.

Then complete the process of writing and verifying the image. When complete, remove the SD card from your PC, insert it into your Raspberry Pi Zero W, and power up the device by inserting a USB cable into the power connector. Note that there are 2 micro USB ports so be sure to connect to the power port.

Connecting to Wi-Fi

Next, we need to determine the IP address of the Raspberry Pi Zero W on your local Wi-Fi network. Typically you could go to the setup page of your router which is usually but may be different for your system. On my Linksys router on the start page, I click on "DHCP Reservation" and I see a screen like this. Look for the Raspberry Pi in the list of devices.

For further information on how to determine the IP address of your Raspberry Pi check out this page from the Raspberry Pi documentation.

Once you have the IP address, you need to use a terminal program to connect to the Raspberry Pi via SSH. I like to use the free program MobaXterm which can be downloaded here. You can also use PuTTY or any other program that can use SSH. MobaXterm is nice because it also lets you use SFTP to easily transfer files. We also will be recommending you set up your Raspberry Pi with a samba server which will make file transfers much easier. Here's a link on how to use PuTTY to connect to your Raspberry Pi.

Here is more information about how to use SSH to connect to a Raspberry Pi and includes specific suggestions for other operating systems besides Windows.

When you have connected via SSH, you should log in using the username "pi" and the password that you specified for SSH when you did the initial installation on the SD card. If you're using PuTTY you will get a pop-up warning the first time you connect. You can ignore the warning.

Initial Configuration

One of the first things you should always do with a new Linux installation is to make sure that everything is up-to-date using the following 2 commands. This can take several minutes.

sudo apt-get update
sudo apt-get upgrade

Next we need to run the Raspberry Pi configuration program with the command

sudo raspi-config

You will then see a screen like this. Choose the third option "Interface Options"

Go down to the 6th item to configure the serial port UART. We need to tell it not to use the serial port for shell commands but to enable the UART. This is how we will communicate between the Raspberry Pi and the QT Py Hat.

After selecting item P6 you will see the following screen to which you should answer "No"

On the next screen answer "Yes". When finished you may wish to enable other options on the screen such as turning on access to SPI, I2C, 1-Wire, and Remote GPIO. Note however none of those other interfaces are necessary for this particular project but they may be useful for other applications of the QT Py Hat.

When you go back to the main menu of the raspi-config program we recommend you choose option 6 "Advanced Options" And then choose option "A1 Expand Filesystem". Although this project requires minimal space on your SD card, we've always found it handy to expand the filesystem on any Raspberry Pi set up.

Enabling Samba Server

Although not completely necessary for this project, we also recommend setting up your Raspberry Pi with a samba server. This will allow you to easily access the file system of your device as if it was another computer on your network. You can drag-and-drop files, create folders, and edit files directly from your PC.

Issue the following command via SSH on your Raspberry Pi

sudo apt-get install samba samba-common-bin

This command will take several minutes to execute. There will be some error messages which you can ignore. At one point during installation, you will see the following pop-up message to which you should answer "Yes".

You will then need to edit the samba configuration file to tell it which folder(s) that you wish to share over your local network. I like using the "nano" editor but if you are more familiar with other editors on Linux systems you can use anyone you like. We will use the following command

sudo nano /etc/samba/smb.conf

Scroll all the way to the bottom of the file. Note it is approximately 200 lines long. Add the following text to the end of the /etc/samba/smb.conf file.

This will make your entire user "pi" file system available. If you don't want to expose that much of your device over the samba interface you can create a folder and only share it.

Comment = Pi shared folder
Path = /home/pi
Browseable = yes
Writeable = Yes
only guest = no
create mask = 0777
directory mask = 0777
Public = yes
Guest ok = yes

Save the file using CTRL-O and exit using CTRL-X (or whatever commands on the editor you might use). Then reboot the system using this command

sudo reboot

After the reboot, you should be able to access the file system of your Raspberry Pi user "pi" file system with your File Explorer on your PC. The file system will be available at \\raspberrypi or if you changed your hostname during set up it will be available under that name. That device should contain a folder userpi. Now you can simply drag-and-drop files or browse files and edit files from that location directly.

Installing Files

In the GitHub repository that you downloaded, there is a folder raspberry_pi_files. It contains a folder named qtpyir. Transfer the entire qtpyir folder and all its subfolders and contents onto your /home/pi directory on the Raspberry Pi. You can drag-and-drop it via the samba connection or upload it using SFTP if you are using MobaXterm.

After you have transferred the files, you need to set permissions on all of them with the following command:

sudo chmod -R 777 /home/pi/qtpyir

Installing Flask

This project makes use of a Python3 library known as "flask". It allows us to serve webpages without needing to install an entire Web server such as Apache. Flask may already be installed on your system but you should still type the following command one time just to make sure.

pip install Flask

Disabling Bluetooth

The default setup for a Raspberry Pi Zero W is that Bluetooth communication takes place over the primary UART. However, we will be using the primary UART for communication between the Raspberry Pi Zero W and the QT Py board. Therefore, we must disable Bluetooth on the Raspberry Pi Zero W. Use the following command or similar to edit /boot/config.txt

sudo nano /boot/config.txt

Add the following line at the very bottom:


Press CTRL-O to write the file and CTRL-X to exit the nano editor. When you have finished you should reboot the system with

sudo reboot

Testing the Python App

After you have rebooted the system issue the following command to start up the Python Flask app that will serve our webpage.

sudo python3 /home/pi/qtpyir/

Earlier we had to determine the IP address of our Raspberry Pi Zero W on our local Wi-Fi network. You should now call up a browser on your PC and navigate to that IP address. For example, when I was testing, my IP address was

You should then see a page pop-up that looks like this:

At this point the webpage will not do anything because it is designed to communicate with the QT Py Hat but at least we know that the web service is working. The command we issued however is only temporary. We need a way to run that command at the start of every reboot and to keep the program running in the background continuously.

To terminate the app that we just launched so that we can do some other things, press CTRL-C on the command line. That will terminate the process.

To make the app run automatically on each reboot we are going to edit the /etc/rc.local file as follows.

sudo nano /etc/rc.local

At the bottom of the file above the line that says exit 0 add the following text.

sudo python3 /home/pi/qtpyir/ &

Note that this is the same command that we used to initialize the server app when we tested it a moment ago except we have added an "&" at the end. This tells the program to run in the background and release control back to the command line. Now save the file with CTRL-O and exit with CTRL-X then reboot your system with

sudo reboot

After the system is rebooted, try pointing your browser at the IP address again and make sure that the webpage serves properly.

This guide was first published on Apr 17, 2021. It was last updated on Mar 08, 2024.

This page (Raspberry Pi Zero W Software and Setup) was last updated on Mar 08, 2024.

Text editor powered by tinymce.