
My favorite Raspberry Pi add-on is the PiTFT from Adafruit. With it, you easily get a Raspberry Pi GUI interface and touch screen. The PiTFT software install is just a few things and it is good to go.
This screen is what I needed in my IoT project. The Pi+Screen will act as the primary controller for all of my things. The problem is I didn’t know much about writing GUI applications in Linux. So what could I do to create a Raspberry Pi GUI?
Python is popular in Pi projects, so I decided to stick with it and find out what GUI toolkits are ready to go. “Ready to go” means they install easily on Raspian and work well on the Pi.
Here is how I got Qt5 for Python up and running to create a Raspberry Pi GUI.
Raspberry Pi GUI Libraries
If you start with this article on dice.com, you’ll find five potential python toolkits.
Not listed there is TkInter, which is the most used Python toolkit. If you have Python running on your system, you have TkInter. I decided not to use it though because the widgets have a very dated look to them.
The other toolkit I considered was wxPython. The UI widgets have a modern feel, though they not entirely native looking. Also plenty of documentation exists. However, I had some trouble getting wxGlade running, which is a WYSIWYG GUI editor.
This lead me to Qt.
Why Qt for Raspberry Pi GUI
In college, I used Qt for my senior design project: an electronic notebook. It was a PC with a 10” touch screen. You could write on it, and it’d save what you write, about ten years before Apple did it.
Having a little bit of familiarity with Qt, I looked into its Python bindings and was happy. I decided on the PyQt binding from Riverbank to go along with Qt5.
Note about licensing PyQt and Qt
PyQt is available as GPL or Commercial License while Qt is available under LGPL or Commercial license. I know even the mere mention of “commercial” will cause some people to turn away. And that’s fine. Qt is modern, and it’s free (since I’m not developing anything commercial.)
If you want “pure” open source, then you might be happier with wxPython.
Development and Production
While the Raspberry Pi is a perfectly capable computer, I found developing on a 3.2” TFT a bit cumbersome. So I wanted to use my laptop “for development” and then deploy the code to my Pi when done.
In my case, I found it pretty easy to duplicate the Python/Qt environment on both.
Installing Python3
It wasn’t clear to me if Qt5 worked with the python2.7. I ran into problems and decided to use python3 instead.
Mac (aka PC) Instructions
Whether you’re on a Mac, Windows, or Linux, get python3 and Qt5 installed. I don’t have much to say about Windows or Linux but on the Mac, install python3 and Qt5 with homebrew.
Simple command:
brew install python3 brew install qt5
If you know all the directories, you can probably get away without re-installing these. However, I like that with the homebrew install; they can find each other.
Next you need PyQt5, which installation varies by operation system.
On Mac, use homebrew:
brew install pyqt5
On Linux, check your package manager. The PyQt5 download page has binaries for Windows.
Raspberry Pi Instructions
Assuming you’re running Raspian Jessie, you can install all three with apt-get:
sudo apt-get install python3 python3-pyqt5
I’m no apt-get expert, but “python3-pyqt5” might be enough to drag along python3.
Download QtCreator
On the PC you plan to develop from, download and install QtCreator. You can download that from Qt, after answering some questions about how you plan to use it.
Believe it or not, I think getting python3, Qt5, and PyQt5 installed is the hardest part. After that, it’s just a matter of copy/paste to get a GUI up and running.
Making a GUI in QtCreator
Start a new project in QtCreator and select “Desktop Application.”
Where you save it, is up to you. (Note, OSX when selecting a directory, the “New Project” window gets hidden. It’s behind the initial QtCreator window.) On kit selection, I have been sticking with “Desktop Qt 5.5.1 clang 64bit.” No need to select the others. QtCreator is going to try and create a C++ program, but the only thing we are interested in is the MainWindow.ui file. So double-click that to open the GUI Editor.
Last you need to name the class for your program. For this tutorial, leave it as “MainWindow.” That way the name will match up with the Python stuff later.
Finally, select none for version control and QtCreator going to create a C++ framework.
The only thing we are interested in is the MainWindow.ui file. So double-click that to open the GUI Editor. At this point, you’re going to add the GUI elements to create whatever GUI you want. I’m not going to go into depth about the different widgets or how they work. Plenty of better tutorials on those.
Instead, here are the critical things to know when creating your Raspberry Pi GUI.
- Set the Window to your Screen Size
- Pay attention to the widget name
- Set defaults for elements
1. Window Size / Screen Size
In my case, I am using the 3.5” PiTFT. Using screen means I have 460 by 320 pixels available. This resolution is taking into account LXDE’s menubar. So I made sure to set my Window to that size.
2. Widget Name
Here’s where my hardware background shows. I’m not sure what the right naming convention to use for widget elements. However, 25 years ago when I was forced to learn VisualBasic, I learned the “xxxNamey” convention. In this case, “xxx” is a three letter abbreviation for the widget style and “y” is the numeric element. So for a button it might be “btnOK1” or “btnRedOn1” and a Text Box would be “txtName1”.
If you know a better method, let me know. I encourage this one because it makes the code read easier later on.
In this code I created two buttons “On” and “Off” named “btnOn” and “btnOff” respectively.
3. Set Defaults
Even if you plan for your program/script to fill in values in the GUI, make sure you set appropriate defaults. For example “PushButton” is a label text for the button. You CAN change in your code, but why not set it now?
Create the GUI Code
Once you have drawn your GUI elements, it is time to generate the matching Python code. Now, don’t worry if your GUI isn’t “done.” You can repeat the following steps as many times as you want.
In QtCreator, just save your GUI. It will update the MainWindow.ui file. In a terminal (or command shell for Windows), we’re going to make use of the pyuic5 utility. On Mac and Unix, here’s your command:
pyuic5 mainwindow.ui > mainwindow_auto.py
Name the result whatever you want, I keep the name mostly the same. Each time you update the GUI in QtCreator, you’ll want to run pyuic5 to update the “auto.py” file.
Okay, you’re asking, are we done yet? Do we have a GUI? Yes and no. This code will run and create a GUI, but that’s not quite enough yet.
Add Basic Python Code
Create a new Python file in the same directory as your mainwindow_auto.py, with this initialization code. Not that it matters really, but I name my main python a very clever name: “main.py”. I know, right?
# always seem to need this import sys # This gets the Qt stuff import PyQt5 from PyQt5.QtWidgets import * # This is our window from QtCreator import mainwindow_auto # create class for our Raspberry Pi GUI class MainWindow(QMainWindow, mainwindow_auto.Ui_MainWindow): # access variables inside of the UI's file def __init__(self): super(self.__class__, self).__init__() self.setupUi(self) # gets defined in the UI file # I feel better having one of these def main(): # a new app instance app = QApplication(sys.argv) form = MainWindow() form.show() # without this, the script exits immediately. sys.exit(app.exec_()) # python bit to figure how who started This if __name__ == "__main__": main()
With just those bits, you can run your new Python script and have basic GUI functions. Of course buttons and other widgets won’t know what to do yet, but you can click them.
python3 main.py
And here’s my GUI:
Add Handlers
Remember when I said to pay attention to the widget names you create? This bit of code is why. Now we need to create handlers in the Python code for each button and widget. In your main.py file, you need to add some functions to your MainWindow class.
# create class for our Raspberry Pi GUI class MainWindow(QMainWindow, mainwindow_auto.Ui_MainWindow): # access variables inside of the UI's file ### functions for the buttons to call def pressedOnButton(self): print ("Pressed On!") def pressedOffButton(self): print ("Pressed Off!") def __init__(self): super(self.__class__, self).__init__() self.setupUi(self) # gets defined in the UI file ### Hooks to for buttons self.btnOn.clicked.connect(lambda: self.pressedOnButton()) self.btnOff.clicked.connect(lambda: self.pressedOffButton())
Replace the MainWindow class from the minimal example before with this code. When it runs a message will be printed on the console with each button press.
In this case, I’m only going to provide button examples. With a little bit of Google-fu, you can find example code for other widget types.
Running on startup
Okay if you’ve already configured the Pi to boot into X-Windows when it starts up, you might want to know how to make your python program run. Well first make sure your “main.py” and “mainwindow_auto.py” files are in the same directory. In my case, I leave them in my “pi” user’s home directory.
Edit this file:
nano /home/pi/.config/lxsession/LXDE-pi/autostart
And add this line:
@/usr/bin/python3 /home/pi/main.py
Now issue a sudo reboot and it should load. (Note, you can use the “which” command to verify the location of the python3 binary.)
Download The Entire project
In case you want to download my Qt and Python code, here is a download button.
Conclusion
As I said, I think the most difficult thing in this tutorial is getting all of the pieces installed—in two places.
That isn’t to say creating the proper handlers for the widgets is easy. However, there are tons (and tons) of help on how to build Qt programs—even if it the code is in C++.
Is your project running on raw framebuffer or do you need startx?
Running through X
Do you know if it is possible to run QT libraries directly on framebuffer, without X window system? Similar to pygame.
TKinter has native widgets with TTK is very easy to use and cross plattform.
/Library/Frameworks/Python.framework/Versions/3.5/bin/python3.5: Error while finding spec for ‘PyQt5.uic.pyuic’ (: No module named ‘PyQt5’)
this error is shucking , please give possible solution
Did you install python through homebrew? If so, make sure you are calling the pyuic5 located in /usr/local/bin
yes, i installed python using homebrew, i dont know how but, after restarting my mac ,its working. thanks buddy
Can we use some lightweight GUI toolkit? Pls suggest one
Hi James, Fantastic tutorial – thank you.
I am trying to build off this customise the button look using style sheets. While it displays correctly on my computer, when i run main.py, the GUI comes up blank (buttons still work but don’t appear). Do you know how to customise the button and still export through python?
Cheers,
Tom
Thanks for the tutorial. I tried to move the files to my RPI, and when I try to run the main.py with: python 3 main.py, I get the following error message:
QXcbConnection: Could not connect to display
Aborted
I am using a Raspberry Pi 2 with the 3.5″ PiTFT. Not sure if I need to define the screen being used somewhere.
Thanks,
If you used the Adafruit directions, you might have added these two lines into your .profile, which a terminal when it starts its shell:
export FRAMEBUFFER=/dev/fb1
export DISPLAY=:0
I had ssh display connection issues when I left those in, so I commented them out. Nothing seemed to break. Maybe give that a shot.
#export FRAMEBUFFER=/dev/fb1
#export DISPLAY=:0
I’ve got the same issue, but I don’t even have those lines in my .profile file. Any ideas?
It seems to work if I call main.py through once I’ve run startx (or through a tightVNC window), but it’s through ssh that it doesn’t work (and that’s how I want to do it…)
When you login with SSH, run “echo $DISPLAY”. Do it return anything?
I was able to solve the problem. I reformatted the SD card a few times, but it was a problem with the display not being defined.
In my original setup from Adafruit it never had the “export DISPLAY=:0”
line in my profile. When I ran echo $DISPLAY with SSH it would return a blank value. But when I ran echo $DISPLAY with Tight VNC, it would return :1
So I decided to add that line into my profile, and it worked. Here are my steps for adding a display. So far everything seems to be functioning.
– sudo nano ~/.profile
– I added the following line to the end: export DISPLAY=:0
– Reboot: sudo reboot <–This is a must!!!!!
– Run the main.py file
It worked through SSH – at least for me.
@James Lewis
Thanks for posting the echo $DISPLAY command line!
I also get the error message “QXcbConnection: Could not connect to display” when I use ssh. Those two lines make no difference if they are there or not, just the returned value of “echo $DISPLAY” changes from empty line to “:0”. Do you got an idea?
Did you manage to solve this issue? Getting the same error in my setup with the official raspberry pi 7 inch touchscreen.
Not yet. I use the raspi 7 inch touchscreen, too. But I even tried to use a normal PC-Monitor connected with HDMI, doesnt work either…
When I open startx, then open a terminal and then run python3 mainwindow.py then it does work.
Is this the way it is supposed to be or should it work through ssh as well?
I don’t know what your mainwindow.py includes. If it follows the code in my example’s “main.py”, then yes, it should work.
When I try to run “pyuic5 mainwindow.ui > mainwindow_auto.py” I get the error (: No module named ‘PyQt5’). Any ideas?
You might have only installed Qt5 for Python 2.7 and not Python 3. “pyuic5” is just a script that calls python
exec python3.5 -m PyQt5.uic.pyuic ${1+"[email protected]"}
To avoid issues, I installed Qt5 for both versions of Python.
How do I set which Python Qt5 gets installed? If I use brew again, it says that Qt5 is already installed.
Use which to see if you have multiple versions of pyuic5 installed on your machine.
which pyuic5
On my machine, I only have one:
/usr/local/bin/pyuic5
I’m pretty sure that is where brew installs by default.
Then use cat to see if one of them is using python3:
cat /usr/local/bin/pyuic5
Try calling the command with python3, contained in the pyuic5 script.
I found what I think is causing the problem. Unfortunately, I don’t understand the explanations on the web on how to fix it. When I try to run configure.pi for PyQt5 I get the following message:”Error: Use the –qmake argument to explicitly specify a working Qt make.”
Sorry, I have no idea what that means. The steps in my post are all I did.
You need to follow the pattern of the line here
python3 configure.py –qmake ~/Qt/5.7/clang_64/bin/qmake
This is from a Mac but basically add –qmake and replace with path to qmake thats part of the Qt stuff
I got the same issue. In my case i figured out that the problem is that pyuic5 tries to execute python2.7 instead of python3! (probably because I have both installed)
I first did:
which pyuic5
To find where is this pyuic5 located (it is in my anaconda distibution file). Then I check what is inside with
cat pyuic5
I get
#!/bin/sh
exec pythonw2.7 -m PyQt5.uic.pyuic ${1+”[email protected]”}
I then use nano to change the pythonw2.7 part with python3 and it works! All the joy!
You can still use Qt on commercial projects for free. What the license says is that you have to share your changes to Qt source code.
Your link to wdGlade seems to have a typo: http://wxglade.sourceforget.net/
sourceforgeT??
Thanks, fixed.
@James: nice article overall, a strait recipe for developing applications to run on Raspberry Pi with a decent GUI.
Regarding the name convention for widgets, I agree with you not to use the names from Qt Creator, and being myself a long time Qt developer, I follow most the same convention as you. Having a 3 or 4 letter prefix for the widget type (btn button, ledt lineedit, cbox checkbox and so on) I however avoid using the y number, as I try to use a name based on the purpose (ledtAddress, ledtName, btnOk, btnCancel). It’s very unlikely you end up with several buttons having the same purpose or label.