Martin Fitzpatrick - python

6th Edition - Create GUI Applications with Python & Qt, Released — PyQt6 & PySide6 Books updated for 2025 with model view controller architecture, new Python/Qt features and more examples

2025-06-12T08:00:00+00:00

The 6th edition of my book Create GUI Applications with Python & Qt is now available, for PyQt6 & PySide6.

This update brings the book up to date with the latest changes in PyQt6 & PySide6, and also updates code to make use of newer features in Python. Many of the chapters have been updated and extended with more examples of form layouts, built-in dialogs and architecture, particularly using Model View Controller (MVC) architecture.

You can buy the latest editions below --

As always, if you've previously bought a copy of the book you get these updates for free! Just go to your account downloads page and enter the email you used for the purchase.

If you bought the book elsewhere (in paperback or digital) you can register to get these updates too -- just email your receipt to register@pythonguis.com

Enjoy!

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

PyQt6 Book now available in Korean: 파이썬과 Qt6로 GUI 애플리케이션 만들기 — The hands-on guide to creating GUI applications with Python gets a new translation

2023-05-04T09:00:00+00:00

I am very happy to announce that my Python GUI programming book Create GUI Applications with Python & Qt6 / PyQt6 Edition is now available in Korean from Acorn Publishing

It's more than a little mind-blowing to see a book I've written translated into another language -- not least one I cannot remotely understand! When I started writing this book a few years ago I could never have imagined it would end up on book shelves in Korea, never mind in Korean. This is just fantastic.

파이썬과 Qt6로 GUI 애플리케이션 만들기 파이썬 애플리케이션 제작 실습 가이드

If you're in Korea, you can also pick up a copy at any of the following bookstores: Kyobobook, YES24 or Aladin

Thanks again to Acorn Publishing for translating my book and making it available to readers in Korea.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

Getting Started With Git and GitHub in Your Python Projects — Version-Controlling Your Python Projects With Git and GitHub

2023-03-20T06:00:00+00:00

Using a version control system (VCS) is crucial for any software development project. These systems allow developers to track changes to the project's codebase over time, removing the need to keep multiple copies of the project folder.

VCSs also facilitate experimenting with new features and ideas without breaking existing functionality in a given project. They also enable collaboration with other developers that can contribute code, documentation, and more.

In this article, we'll learn about Git, the most popular VCS out there. We'll learn everything we need to get started with this VCS and start creating our own repositories. We'll also learn how to publish those repositories to GitHub, another popular tool among developers nowadays.

Installing and Setting Up Git

To use Git in our coding projects, we first need to install it on our computer. To do this, we need to navigate to Git's download page and choose the appropriate installer for our operating system. Once we've downloaded the installer, we need to run it and follow the on-screen instructions.

We can check if everything is working correctly by opening a terminal or command-line window and running git --version.

Once we've confirmed the successful installation, we should provide Git with some personal information. You'll only need to do this once for every computer. Now go ahead and run the following commands with your own information:

shell

$ git config --global user.name <"YOUR NAME">
$ git config --global user.email <name@email.com>

The first command adds your full name to Git's config file. The second command adds your email. Git will use this information in all your repositories.

If you publish your projects to a remote server like GitHub, then your email address will be visible to anyone with access to that repository. If you don't want to expose your email address this way, then you should create a separate email address to use with Git.

As you'll learn in a moment, Git uses the concept of branches to manage its repositories. A branch is a copy of your project's folder at a given time in the development cycle. The default branch of new repositories is named either master or main, depending on your current version of Git.

You can change the name of the default branch by running the following command:

shell

$ git config --global init.defaultBranch <branch_name>

This command will set the name of Git's default branch to branch_name. Remember that this is just a placeholder name. You need to provide a suitable name for your installation.

Another useful setting is the default text editor Git will use to type in commit messages and other messages in your repo. For example, if you use an editor like Visual Studio Code, then you can configure Git to use it:

shell

# Visual Studio Code
$ git config --global core.editor "code --wait"

With this command, we tell Git to use VS Code to process commit messages and any other message we need to enter through Git.

Finally, to inspect the changes we've made to Git's configuration files, we can run the following command:

shell

$ git config --global -e

This command will open the global .gitconfig file in our default editor. There, we can fix any error we have made or add new settings. Then we just need to save the file and close it.

Understanding How Git Works

Git works by allowing us to take a snapshot of the current state of all the files in our project's folder. Each time we save one of those snapshots, we make a Git commit. Then the cycle starts again, and Git creates new snapshots, showing how our project looked like at any moment.

Git was created in 2005 by Linus Torvalds, the creator of the Linux kernel. Git is an open-source project that is licensed under the GNU General Public License (GPL) v2. It was initially made to facilitate kernel development due to the lack of a suitable alternative.

The general workflow for making a Git commit to saving different snapshots goes through the following steps:

Change the content of our project's folder.
Stage or mark the changes we want to save in our next commit.
Commit or save the changes permanently in our project's Git database.

As the third step mentions, Git uses a special database called a repository. This database is kept inside your project's directory under a folder called .git.

Version-Controlling a Project With Git: The Basics

In this section, we'll create a local repository and learn how to manage it using the Git command-line interface (CLI). On macOS and Linux, we can use the default terminal application to follow along with this tutorial.

On Windows, we recommend using Git Bash, which is part of the Git For Windows package. Go to the Git Bash download page, get the installer, run it, and follow the on-screen instruction. Make sure to check the Additional Icons -> On the Desktop to get direct access to Git Bash on your desktop so that you can quickly find and launch the app.

Alternatively, you can also use either Windows' Command Prompt or PowerShell. However, some commands may differ from the commands used in this tutorial.

Initializing a Git Repository

To start version-controlling a project, we need to initialize a new Git repository in the project's root folder or directory. In this tutorial, we'll use a sample project to facilitate the explanation. Go ahead and create a new folder in your file system. Then navigate to that folder in your terminal by running these commands:

shell

$ mkdir sample_project
$ cd sample_project

The first command creates the project's root folder or directory, while the second command allows you to navigate into that folder. Don't close your terminal window. You'll be using it throughout the next sections.

To initialize a Git repository in this folder, we need to use the git init command like in the example below:

shell

$ git init
Initialized empty Git repository in /.../sample_project/.git/

This command creates a subfolder called .git inside the project's folder. The leading dot in the folder's name means that this is a hidden directory. So, you may not see anything on your file manager. You can check the existence of .git with the ls -a, which lists all files in a given folder, including the hidden ones.

Checking the Status of Our Project

Git provides the git status command to allow us to identify the current state of a Git repository. Because our sample_project folder is still empty, running git status will display something like this:

shell

$ git status
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

When we run git status, we get detailed information about the current state of our Git repository. This command is pretty useful, and we'll turn back to it in multiple moments.

As an example of how useful the git status command is, go ahead and create a file called main.py inside the project's folder using the following commands:

shell

$ touch main.py

$ git status
On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    main.py

nothing added to commit but untracked files present (use "git add" to track)

With the touch command, we create a new main.py file under our project's folder. Then we run git status again. This time, we get information about the presence of an untracked file called main.py. We also get some basic instructions on how to add this file to our Git repo. Providing these guidelines or instructions is one of the neatest features of git status.

Now, what is all that about untracked files? In the following section, we'll learn more about this topic.

Tracking and Committing Changes

A file in a Git repository can be either tracked or untracked. Any file that wasn't present in the last commit is considered an untracked file. Git doesn't keep a history of changes for untracked files in your project's folder.

In our example, we haven't made any commits to our Git repo, so main.py is naturally untracked. To start tracking it, run the git add command as follows:

shell

$ git add main.py

$ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   main.py

This git add command has added main.py to the list of tracked files. Now it's time to save the file permanently using the git commit command with an appropriate commit message provided with the -m option:

shell

$ git commit -m "Add main.py"
[main (root-commit) 5ac6586] Add main.py
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 main.py

$ git status
On branch master
nothing to commit, working tree clean

We have successfully made our first commit, saving main.py to our Git repository. The git commit command requires a commit message, which we can provide through the -m option. Commit messages should clearly describe what we have changed in our project.

After the commit, our main branch is completely clean, as you can conclude from the git status output.

Now let's start the cycle again by modifying main.py, staging the changes, and creating a new commit. Go ahead and run the following commands:

shell

$ echo "print('Hello, World!')" > main.py
$ cat main.py
print('Hello, World!')

$ git add main.py

$ git commit -m "Create a 'Hello, World!' script  on  main.py"
[main 2f33f7e] Create a 'Hello, World!' script  on  main.py
 1 file changed, 1 insertion(+)

The echo command adds the statement "print('Hello, World!')" to our main.py file. You can confirm this addition with the cat command, which lists the content of one or more target files. You can also open main.py in your favorite editor and update the file there if you prefer.

We can also use the git stage command to stage or add files to a Git repository and include them in our next commit.

We've made two commits to our Git repo. We can list our commit history using the git log command as follows:

shell

$ git log --oneline
2f33f7e (HEAD -> main) Create a 'Hello, World!' script  on  main.py
5ac6586 Add main.py

The git log command allows us to list all our previous commits. In this example, we've used the --oneline option to list commits in a single line each. This command takes us to a dedicated output space. To leave that space, we can press the letter Q on our keyboard.

Using a `.gitignore` File to Skip Unneeded Files

While working with Git, we will often have files and folders that we must not save to our Git repo. For example, most Python projects include a venv/ folder with a virtual environment for that project. Go ahead and create one with the following command:

shell

$ python -m venv venv

Once we've added a Python virtual environment to our project's folder, we can run git status again to check the repo state:

shell

$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    venv/

nothing added to commit but untracked files present (use "git add" to track)

Now the venv/ folder appears as an untracked file in our Git repository. We don't need to keep track of this folder because it's not part of our project's codebase. It's only a tool for working on the project. So, we need to ignore this folder. To do that, we can add the folder to a .gitignore file.

Go ahead and create a .gitignore file in the project's folder. Add the venv/ folders to it and run git status:

shell

$ touch .gitignore
$ echo "venv/" > .gitignore
$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    .gitignore

nothing added to commit but untracked files present (use "git add" to track)

Now git status doesn't list venv/ as an untracked file. This means that Git is ignoring that folder. If we take a look at the output, then we'll see that .gitignore is now listed as an untracked file. We must commit our .gitignore files to the Git repository. This will prevent other developers working with us from having to create their own local .gitignore files.

We can also list multiple files and folders in our .gitignore file one per line. The file even accepts glob patterns to match specific types of files, such as *.txt. If you want to save yourself some work, then you can take advantage of GitHub's gitignore repository, which provides a rich list of predefined .gitignore files for different programming languages and development environments.

We can also set up a global .gitignore file on our computer. This global file will apply to all our Git repositories. If you decide to use this option, then go ahead and create a .gitignore_global in your home folder.

Working With Branches in Git

One of the most powerful features of Git is that it allows us to create multiple branches. A branch is a copy of our project's current status and commits history. Having the option to create and handle branches allows us to make changes to our project without messing up the main line of development.

We'll often find that software projects maintain several independent branches to facilitate the development process. A common branch model distinguishes between four different types of branches:

A main or master branch that holds the main line of development
A develop branch that holds the last developments
One or more feature branches that hold changes intended to add new features
One or more bugfix branches that hold changes intended to fix critical bugs

However, the branching model to use is up to you. In the following sections, we'll learn how to manage branches using Git.

Creating New Branches

Working all the time on the main or master branch isn't a good idea. We can end up creating a mess and breaking the code. So, whenever we want to experiment with a new idea, implement a new feature, fix a bug, or just refactor a piece of code, we should create a new branch.

To kick things off, let's create a new branch called hello on our Git repo under the sample_project folder. To do that, we can use the git branch command followed by the branch's name:

shell

$ git branch hello
$ git branch --list
* main
  hello

The first command creates a new branch in our Git repo. The second command allows us to list all the branches that currently exist in our repository. Again, we can press the letter Q on our keyboard to get back to the terminal prompt.

The star symbol denotes the currently active branch, which is main in the example. We want to work on hello, so we need to activate that branch. In Git's terminology, we need to check out to hello.

Checking Out to a New Branch

Although we have just created a new branch, in order to start working on it, we need to switch to or check out to it by using the git checkout command as follows:

shell

$ git checkout hello
Switched to branch 'hello'

$ git branch --list
  main
* hello

$ git log --oneline
2f33f7e (HEAD -> hello, main) Create a 'Hello, World!' script  on  main.py
5ac6586 Add main.py

The git checkout command takes the name of an existing branch as an argument. Once we run the command, Git takes us to the target branch.

We can derive a new branch from whatever branch we need.

As you can see, git branch --list indicates which branch we are currently on by placing a * symbol in front of the relevant branch name. If we check the commit history with git log --oneline, then we'll get the same as we get from main because hello is a copy of it.

The git checkout can take a -b flag that we can use to create a new branch and immediately check out to it in a single step. That's what most developers use while working with Git repositories. In our example, we could have run git checkout -b hello to create the hello branch and check out to it with one command.

Let's make some changes to our project and create another commit. Go ahead and run the following commands:

shell

$ echo "print('Welcome to PythonGUIs!')" >> main.py
$ cat main.py
print('Hello, World!')
print('Welcome to PythonGUIs!')

$ git add main.py
$ git commit -m "Extend our 'Hello, World' program with a welcome message."
[hello be62476] Extend our 'Hello, World' program with a welcome message.
 1 file changed, 1 insertion(+)

The final command committed our changes to the hello branch. If we compare the commit history of both branches, then we'll see the difference:

shell

$ git log --oneline -1
be62476 (HEAD -> hello) Extend our 'Hello, World' program with a welcome message.

$ git checkout main
Switched to branch 'main'

$ git log --oneline -1
2f33f7e (HEAD -> main) Create a 'Hello, World!' script  on  main.py

In this example, we first run git log --oneline with -1 as an argument. This argument tells Git to give us only the last commit in the active branch's commit history. To inspect the commit history of main, we first need to check out to that branch. Then we can run the same git log command.

Now say that we're happy with the changes we've made to our project in the hello branch, and we want to update main with those changes. How can we do this? We need to merge hello into main.

Merging Two Branches Together

To add the commits we've made in a separate branch back to another branch, we can run what is known as a merge. For example, say we want to merge the new commits in hello into main. In this case, we first need to switch back to main and then run the git merge command using hello as an argument:

shell

$ git checkout main
Already on 'main'

$ git merge hello
Updating 2f33f7e..be62476
Fast-forward
 main.py | 1 +
 1 file changed, 1 insertion(+)

To merge a branch into another branch, we first need to check out the branch we want to update. Then we can run git merge. In the example above, we first check out to main. Once there, we can merge hello.

Deleting Unused Branches

Once we've finished working in a given branch, we can delete the entire branch to keep our repo as clean as possible. Following our example, now that we've merged hello into main, we can remove hello.

To remove a branch from a Git repo, we use the git branch command with the --delete option. To successfully run this command, make sure to switch to another branch before:

shell

$ git checkout main
Already on 'main'

$ git branch --delete hello
Deleted branch hello (was be62476).

$ git branch --list
* main

Deleting unused branches is a good way to keep our Git repositories clean, organized, and up to date. Also, deleting them as soon as we finish the work is even better because having old branches around may be confusing for other developers collaborating with our project. They might end up wondering why these branches are still alive.

Using a GUI Client for Git

In the previous sections, we've learned to use the git command-line tool to manage Git repositories. If you prefer to use GUI tools, then you'll find a bunch of third-party GUI frontends for Git. While they won't completely replace the need for using the command-line tool, they can simplify your day-to-day workflow.

You can get a complete list of standalone GUI clients available on the Git official documentation.

Most popular IDEs and code editors, including PyCharm and Visual Studio Code, come with basic Git integration out-of-the-box. Some developers will prefer this approach as it is directly integrated with their development environment of choice.

If you need something more advanced, then GitKraken is probably a good choice. This tool provides a standalone, cross-platform GUI client for Git that comes with many additional features that can boost your productivity.

Managing a Project With GitHub

If we publish a project on a remote server with support for Git repositories, then anyone with appropriate permissions can clone our project, creating a local copy on their computer. Then, they can make changes to our project, commit them to their local copy, and finally push the changes back to the remote server. This workflow provides a straightforward way to allow other developers to contribute code to your projects.

In the following sections, we'll learn how to create a remote repository on GitHub and then push our existing local repository to it. Before we do that, though, head over to GitHub.com and create an account there if you don't have one yet. Once you have a GitHub account, you can set up the connection to that account so that you can use it with Git.

Setting Up a Secure Connection to GitHub

In order to work with GitHub via the git command, we need to be able to authenticate ourselves. There are a few ways of doing that. However, using SSH is the recommended way. The first step in the process is to generate an SSH key, which you can do with the following command:

shell

$ ssh-keygen -t ed25519 -C "GitHub - name@email.com"

Replace the placeholder email address with the address you've associated with your GitHub account. Once you run this command, you'll get three different prompts in a row. You can respond to them by pressing Enter to accept the default option. Alternatively, you can provide custom responses.

Next, we need to copy the contents of our id_ed25519.pub file. To do this, you can run the following command:

shell

$ cat ~/.ssh/id_ed25519.pub

Select the command's output and copy it. Then go to your GitHub Settings page and click the SSH and GPG keys option. There, select New SSH key, set a descriptive title for the key, make sure that the Key Type is set to Authentication Key, and finally, paste the contents of id_ed25519.pub in the Key field. Finally, click the Add SSH key button.

At this point, you may be asked to provide some kind of Two-Factor Authentication (2FA) code. So, be ready for that extra security step.

Now we can test our connection by running the following command:

shell

$ ssh -T git@github.com
The authenticity of host 'github.com (IP ADDRESS)' can not be established.
ECDSA key fingerprint is SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Make sure to check whether the key fingerprint shown on your output matches GitHub's public key fingerprint. If it matches, then enter yes and press Enter to connect. Otherwise, don't connect.

If the connection is successful, we will get a message like this:

shell

Hi USERNAME! You have successfully authenticated, but GitHub does not provide shell access.

Congrats! You've successfully connected to GitHub via SSH using a secure SSH key. Now it's time to start working with GitHub.

Creating and Setting Up a GitHub Repository

Now that you have a GitHub account with a proper SSH connection, let's create a remote repository on GitHub using its web interface. Head over to the GitHub page and click the + icon next to your avatar in the top-right corner. Then select New repository.

Give your new repo a unique name and choose who can see this repository. To continue with our example, we can give this repository the same name as our local project, sample_project.

To avoid conflicts with your existing local repository, don't add .gitignore, README, or LICENSE files to your remote repository.

Next, set the repo's visibility to Private so that no one else can access the code. Finally, click the Create repository button at the end of the page.

If you create a Public repository, make sure also to choose an open-source license for your project to tell people what they can and can't do with your code.

You'll get a Quick setup page as your remote repository has no content yet. Right at the top, you'll have the choice to connect this repository via HTTPS or SSH. Copy the SSH link and run the following command to tell Git where the remote repository is hosted:

shell

$ git remote add origin git@github.com:USERNAME/sample_project.git

This command adds a new remote repository called origin to our local Git repo.

The name origin is commonly used to denote the main remote repository associated with a given project. This is the default name Git uses to identify the main remote repo.

Git allows us to add several remote repositories to a single local one using the git remote add command. This allows us to have several remote copies of your local Git repo.

Pushing a Local Git Repository to GitHub

With a new and empty GitHub repository in place, we can go ahead and push the content of our local repo to its remote copy. To do this, we use the git push command providing the target remote repo and the local branch as arguments:

shell

$ git push -u origin main
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (9/9), 790 bytes | 790.00 KiB/s, done.
Total 9 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:USERNAME/sample_project.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

This is the first time we push something to the remote repo sample_project, so we use the -u option to tell Git that we want to set the local main branch to track the remote main branch. The command's output provides a pretty detailed summary of the process.

Note that if you don't add the -u option, then Git will ask what you want to do. A safe workaround is to copy and paste the commands GitHub suggests, so that you don't forget -u.

Using the same command, we can push any local branch to any remote copy of our project's repo. Just change the repo and branch name: git push -u remote_name branch_name.

Now let's head over to our browser and refresh the GitHub page. We will see all of our project files and commit history there.

Now we can continue developing our project and making new commits locally. To push our commits to the remote main branch, we just need to run git push. This time, we don't have to use the remote or branch name because we've already set main to track origin/main.

Pulling Content From a GitHub Repository

We can do basic file editing and make commits within GitHub itself. For example, if we click the main.py file and then click the pencil icon at the top of the file, we can add another line of code and commit those changes to the remote main branch directly on GitHub.

Go ahead and add the statement print("Your Git Tutorial is Here...") to the end of main.py. Then go to the end of the page and click the Commit changes button. This makes a new commit on your remote repository.

This remote commit won't appear in your local commit history. To download it and update your local main branch, use the git pull command:

shell

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 696 bytes | 174.00 KiB/s, done.
From github.com:USERNAME/sample_project
   be62476..605b6a7  main       -> origin/main
Updating be62476..605b6a7
Fast-forward
 main.py | 1 +
 1 file changed, 1 insertion(+)

Again, the command's output provides all the details about the operation. Note that git pull will download the remote branch and update the local branch in a single step.

If we want to download the remote branch without updating the local one, then we can use the [git fetch](https://git-scm.com/docs/git-fetch) command. This practice gives us the chance to review the changes and commit them to our local repo only if they look right.

For example, go ahead and update the remote copy of main.py by adding another statement like print("Let's go!!"). Commit the changes. Then get back to your local repo and run the following command:

shell

$ git fetch
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 731 bytes | 243.00 KiB/s, done.
From github.com:USERNAME/sample_project
   605b6a7..ba489df  main       -> origin/main

This command downloaded the latest changes from origin/main to our local repo. Now we can compare the remote copy of main.py to the local copy. To do this, we can use the git diff command as follows:

shell

$ git diff main origin/main
diff --git a/main.py b/main.py
index be2aa66..4f0e7cf 100644
--- a/main.py
+++ b/main.py
@@ -1,3 +1,4 @@
 print('Hello, World!')
 print('Welcome to PythonGUIs!')
 print("Your Git Tutorial is Here...")
+print("Let's go!!")

In the command's output, you can see that the remote branch adds a line containing print("Let's go!!") to the end of main.py. This change looks good, so we can use git pull to commit the change automatically.

Exploring Alternatives to GitHub

While GitHub is the most popular public Git server and collaboration platform in use, it is far from being the only one. GitLab.com and BitBucket are popular commercial alternatives similar to GitHub. While they have paid plans, both offer free plans, with some restrictions, for individual users.

Although, if you would like to use a completely open-source platform instead, Codeberg might be a good option. It's a community-driven alternative with a focus on supporting Free Software. Therefore, in order to use Codeberg, your project needs to use a compatible open-source license.

Optionally, you can also run your own Git server. While you could just use barebones git for this, software such as GitLab Community Edition (CE) and Forgejo provide you with both the benefits of running your own server and the experience of using a service like GitHub.

Conclusion

By now, you're able to use Git for version-controlling your projects. Git is a powerful tool that will make you much more efficient and productive, especially as the scale of your project grows over time.

While this guide introduced you to most of its basic concepts and common commands, Git has many more commands and options that you can use to be even more productive. Now, you know enough to get up to speed with Git.

Working With Classes in Python — Understanding the Intricacies of Python Classes

2023-03-06T06:00:00+00:00

Python supports object-oriented programming (OOP) through classes, which allow you to bundle data and behavior in a single entity. Python classes allow you to quickly model concepts by creating representations of real objects that you can then use to organize your code.

In this tutorial, you'll learn how OOP and classes work in Python. This knowledge will allow you to quickly grasp how you can use their classes and APIs to create robust Python applications.

Defining Classes in Python

Python classes are templates or blueprints that allow us to create objects through instantiation. These objects will contain data representing the object's state, and methods that will act on the data providing the object's behavior.

Instantiation is the process of creating instances of a class by calling the class constructor with appropriate arguments.

Attributes and methods make up what is known as the class interface or API. This interface allows us to operate on the objects without needing to understand their internal implementation and structure.

Alright, it is time to start creating our own classes. We'll start by defining a Color class with minimal functionality. To do that in Python, you'll use the class keyword followed by the class name. Then you provide the class body in the next indentation level:

python

>>> class Color:
...     pass
...

>>> red = Color()

>>> type(red)
<class '__main__.Color'>

In this example, we defined our Color class using the class keyword. This class is empty. It doesn't have attributes or methods. Its body only contains a pass statement, which is Python's way to do nothing.

Even though the class is minimal, it allows us to create instances by calling its constructor, Colo(). So, red is an instance of Color. Now let's make our Color class more fun by adding some attributes.

Adding Class and Instance Аttributes

Python classes allow you to add two types of attributes. You can have class and instance attributes. A class attribute belongs to its containing class. Its data is common to the class and all its instances. To access a class attribute, we can use either the class or any of its instances.

Let's now add a class attribute to our Color class. For example, let's say we need to keep note of how many instance of Color your code creates. Then you can have a color_count attribute:

python

>>> class Color:
...     color_count = 0
...     def __init__(self):
...         Color.color_count += 1
...

>>> red = Color()
>>> green = Color()

>>> Color.color_count
2
>>> red.color_count
2

Now Color has a class attribute called color_count that gets incremented every time we create a new instance. We can quickly access that attribute using either the class directly or one of its instances, like red.

To follow up with this example, say that we want to represent our Color objects using red, green, and blue attributes as part of the RGB color model. These attributes should have specific values for specific instances of the class. So, they should be instance attributes.

To add an instance attribute to a Python class, you must use the .__init__() special method, which we introduced in the previous code but didn't explain. This method works as the instance initializer because it allows you to provide initial values for instance attributes:

python

>>> class Color:
...     color_count = 0
...     def __init__(self, red, green, blue):
...         Color.color_count += 1
...         self.red = red
...         self.green = green
...         self.blue = blue
...

>>> red = Color(255, 0, 0)

>>> red.red
255
>>> red.green
0
>>> red.blue
0

>>> Color.red
Traceback (most recent call last):
    ...
AttributeError: type object 'Color' has no attribute 'red'

Cool! Now our Color class looks more useful. It has the usual class attributes and also three new instance attributes. Note that, unlike class attributes, instance attributes can't be accessed through the class itself. They're specific to a concrete instance.

There's something that jumps into sight in this new version of Color. What is the self argument in the definition of .__init__()? This attribute holds a reference to the current instance. Using the name self to identify the current instance is a strong convention in Python.

We'll use self as the first or even the only argument to instance methods like .__init__(). Inside an instance method, we'll use self to access other methods and attributes defined in the class. To do that, we must prepend self to the name of the target attribute or method instance of the class.

For example, our class has an attribute .red that we can access using the syntax self.red inside the class. This will return the number stored under that name. From outside the class, you need to use a concrete instance instead of self.

Providing Behavior With Methods

A class bundles data (attributes) and behavior (methods) together in an object. You'll use the data to set the object's state and the methods to operate on that data or state.

Methods are just functions that we define inside a class. Like functions, methods can take arguments, return values, and perform different computations on an object's attributes. They allow us to make our objects usable.

In Python, we can define three types of methods in our classes:

Instance methods, which need the instance (self) as their first argument
Class methods, which take the class (cls) as their first argument
Static methods, which take neither the class nor the instance

Let's now talk about instance methods. Say that we need to get the attributes of our Color class as a tuple of numbers. In this case, we can add an .as_tuple() method like the following:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

This new method is pretty straightforward. Since it's an instance method, it takes self as its first argument. Then it returns a tuple containing the attributes .red, .green, and .blue. Note how you need to use self to access the attributes of the current instance inside the class.

This method may be useful if you need to iterate over the RGB components of your color objects:

python

>>> red = Color(255, 0, 0)
>>> red.as_tuple()
(255, 0, 0)

>>> for level in red.as_tuple():
...     print(level)
...
255
0
0

Our as_tuple() method works great! It returns a tuple containing the RGB components of our color objects.

We can also add class methods to our Python classes. To do this, we need to use the @classmethod decorator as follows:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

The from_tuple() method takes a tuple object containing the RGB components of a desired color as an argument, creates a valid color object from it, and returns the object back to the caller:

python

>>> blue = Color.from_tuple((0, 0, 255))
>>> blue.as_tuple()
(0, 0, 255)

In this example, we use the Color class to access the class method from_tuple(). We can also access the method using a concrete instance of this class. However, in both cases, we'll get a completely new object.

Finally, Python classes can also have static methods that we can define with the @staticmethod decorator:

python

class Color:
    representation = "RGB"

    def __init__(self, red, green, blue):
        self.red = red
        self.green = green
        self.blue = blue

    def as_tuple(self):
        return self.red, self.green, self.blue

    @classmethod
    def from_tuple(cls, rbg):
        return cls(*rbg)

    @staticmethod
    def color_says(message):
        print(message)

Static methods don't operate either on the current instance self or the current class cls. These methods can work as independent functions. However, we typically put them inside a class when they are related to the class, and we need to have them accessible from the class and its instances.

Here's how the method works:

python

>>> Color.color_says("Hello from the Color class!")
Hello from the Color class!

>>> red = Color(255, 0, 0)
>>> red.color_says("Hello from the red instance!")
Hello from the red instance!

This method accepts a message and prints it on your screen. It works independently from the class or instance attributes. Note that you can call the method using the class or any of its instances.

Writing Getter & Setter Methods

Programming languages like Java and C++ rely heavily on setter and getter methods to retrieve and update the attributes of a class and its instances. These methods encapsulate an attribute allowing us to get and change its value without directly accessing the attribute itself.

For example, say that we have a Label class with a text attribute. We can make text a non-public attribute and provide getter and setter methods to manipulate the attributes according to our needs:

python

class Label:
    def __init__(self, text):
        self.set_text(text)

    def text(self):
        return self._text

    def set_text(self, value):
        self._text = str(value)

In this class, the text() method is the getter associated with the ._text attribute, while the set_text() method is the setter for ._text. Note how ._text is a non-public attribute. We know this because it has a leading underscore on its name.

The setter method calls str() to convert any input value into a string. Therefore, we can call this method with any type of object. It will convert any input argument into a string, as you will see in a moment.

If you come from programming languages like Java or C++, you need to know Python doesn't have the notion of private, protected, and public attributes. In Python, you'll use a naming convention to signal that an attribute is non-public. This convention consists of adding a leading underscore to the attribute's name. Note that this naming pattern only indicates that the attribute isn't intended to be used directly. It doesn't prevent direct access, though.

This class works as follows:

python

>>> label = Label("Python!")

>>> label.text()
'Python!'

>>> label.set_text("Classes!")
>>> label.text()
'Classes!'

>>> label.set_text(123)
>>> label.text()
'123'

In this example, we create an instance of Label. The original text is passed to the class constructor, Label(), which automatically calls __init__() to set the value of ._text by calling the setter method text(). You can use text() to access the label's text and set_text() to update it. Remember that any input will be converted into a string, as we can see in the final example above.

The getter and setter pattern is pretty common in languages like Java and C++. However, this pattern is less popular among Python developers. Instead, they use the @property decorator to hide attributes behind properties.

Here's how most Python developer will write their Label class:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

This class defines .text as a property. This property has getter and setter methods. Python calls them automatically when we access the attribute or update its value in an assignment:

python

>>> label = Label("Python!")

>>> label.text
'Python!'

>>> label.text = "Class"
>>> label.text
'Class'

>>> label.text = 123
>>> label.text
'123'

Python properties allow you to add function behavior to your attributes while permitting you to use them as normal attributes instead of as methods.

Writing Special Methods

Python supports many special methods, also known as dunder or magic methods, that are part of its class mechanism. We can identify these methods because their names start and end with a double underscore, which is the origin of their other name: dunder methods.

These methods accomplish different tasks in Python's class mechanism. They all have a common feature: Python calls them automatically depending on the operation we run.

For example, all Python objects are printable. We can print them to the screen using the print() function. Calling print() internally falls back to calling the target object's __str__() special method:

python

>>> label = Label("Python!")

>>> print(label)
<__main__.Label object at 0x10354efd0>

In this example, we've printed our label object. This action provides some information about the object and the memory address where it lives. However, the actual output is not very useful from the user's perspective.

Fortunately, we can improve this by providing our Label class with an appropriate __str__() method:

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

The __str__() method must return a user-friendly string representation for our objects. In this case, when we print an instance of Label to the screen, the label's text will be displayed:

python

>>> label = Label("Python!")

>>> print(label)
Python!

As you can see, Python takes care of calling __str__() automatically when we use the print() function to display our instances of Label.

Another special method that belongs to Python's class mechanism is __repr__(). This method returns a developer-friendly string representation of a given object. Here, developer-friendly implies that the representation should allow a developer to recreate the object itself.

python

class Label:
    def __init__(self, text):
        self.text = text

    @property
    def text(self):
        return self._text

    @text.setter
    def text(self, value):
        self._text = str(value)

    def __str__(self):
        return self.text

    def __repr__(self):
        return f"{type(self).__name__}(text='{self.text}')"

The __repr__() method returns a string representation of the current objects. This string differs from what __str__() returns:

python

>>> label = Label("Python!")
>>> label
Label(text='Python!')

Now when you access the instance on your REPL session, you get a string representation of the current object. You can copy and paste this representation to recreate the object in an appropriate environment.

Reusing Code With Inheritance

Inheritance is an advanced topic in object-oriented programming. It allows you to create hierarchies of classes where each subclass inherits all the attributes and behaviors from its parent class or classes. Arguably, code reuse is the primary use case of inheritance.

Yes, we code a base class with a given functionality and make that functionality available to its subclass through inheritance. This way, we implement the functionality only once and reuse it in every subclass.

Python classes support single and multiple inheritance. For example, let's say we need to create a button class. This class needs .width and .height attributes that define its rectangular shape. The class also needs a label for displaying some informative text.

We can code this class from scratch, or we can use inheritance and reuse the code of our current Label class. Here's how to do this:

python

class Button(Label):
    def __init__(self, text, width, height):
        super().__init__(text)
        self.width = width
        self.height = height

    def __repr__(self):
        return (
            f"{type(self).__name__}"
            f"(text='{self.text}', "
            f"width={self.width}, "
            f"height={self.height})"
        )

To inherit from a parent class in Python, we need to list the parent class or classes in the subclass definition. To do this, we use a pair of parentheses and a comma-separated list of parent classes. If we use several parent classes, then we're using multiple inheritance, which can be challenging to reason about.

The first line in __init__() calls the __init__() method on the parent class to properly initialize its .text attribute. To do this, we use the built-in super() function. Then we define the .width and .height attributes, which are specific to our Button class. Finally, we provide a custom implementation of __repr__().

Here's how our Button class works:

python

>>> button = Button("Ok", 10, 5)

>>> button.text
'Ok'
>>> button.text = "Click Me!"
>>> button.text
'Click Me!'

>>> button.width
10
>>> button.height
5

>>> button
Button(text='Ok', width=10, height=5)
>>> print(button)
Click Me!

As you can conclude from this code, Button has inherited the .text attribute from Label. This attribute is completely functional. Our class has also inherited the __str__() method from Label. That's why we get the button's text when we print the instance.

As we've seen, Python allows us to write classes that work as templates that you can use to create concrete objects that bundle together data and behavior. The building blocks of Python classes are:

Attributes, which hold the data in a class
Methods, which provide the behaviors of a class

The attributes of a class define the class's data, while the methods provide the class's behaviors, which typically act on that data.

To better understand OOP and classes in Python, we should first discuss some terms that are commonly used in this aspect of Python development:

Classes are blueprints or templates for creating objects -- just like a blueprint for creating a car, plane, house, or anything else. In programming, this blueprint will define the data (attributes) and behavior (methods) of the object and will allow us to create multiple objects of the same kind.
Objects or Instances are the realizations of a class. We can create objects from the blueprint provided by the class. For example, you can create John's car from a Car class.
Methods are functions defined within a class. They provide the behavior of an object of that class. For example, our Car class can have methods to start the engine, turn right and left, stop, and so on.
Attributes are properties of an object or class. We can think of attributes as variables defined in a class or object. Therefore, we can have:
- class attributes, which are specific to a concrete class and common to all the instances of that class. You can access them either through the class or an object of that class. For example, if we're dealing with a single car manufacturer, then our Car class can have a manufacturer attribute that identifies it.
- instance attributes, which are specific to a concrete instance. You can access them through the specific instance. For example, our Car class can have attributes to store properties such as the maximum speed, the number of passengers, the car's weight, and so on.
Instantiation is the process of creating an individual instance from a class. For example, we can create John's car, Jane's car, and Linda's car from our Car class through instantiation. In Python, this process runs through two steps:
1. Instance creation: Creates a new object and allocates memory for storing it.
2. Instance initialization: Initializes all the attributes of the current object with appropriate values.
Inheritance is a mechanism of code reuse that allows us to inherit attributes and methods from one or multiple existing classes. In this context, we'll hear terms like:
- Parent class: The class we're inheriting from. This class is also known as the superclass or base class. If we have one parent class, then we're using single inheritance. If we have more than one parent class, then we're using multiple inheritance.
- Child class: The class that inherits from a given parent. This class is also known as the subclass.

Don't feel frustrated or bad if you don't understand all these terms immediately. They'll become more familiar with use as you use them in your own Python code.

Conclusion

Now you know the basics of Python classes. You also learned fundamental concepts of object-oriented programming, such as inheritance.

Getting started with VS Code for Python — Setting up a Development Environment for Python programming

2022-09-21T09:00:00+00:00

Setting up a working development environment is the first step for any project. Your development environment setup will determine how easy it is to develop and maintain your projects over time. That makes it important to choose the right tools for your project. This article will guide you through how to set up Visual Studio Code, which is a popular free-to-use, cross-platform code editor developed by Microsoft, in order to develop Python applications.

Visual Studio Code is not to be confused with Visual Studio, which is a separate product also offered by Microsoft. Visual Studio is a fully-fledged IDE that is mainly geared towards Windows application development using C# and the .NET Framework.

Setup a Python environment

In case you haven't already done this, Python needs to be installed on the development machine. You can do this by going to python.org and grabbing the specific installer for either Windows or macOS. Python is also available for installation via Microsoft Store on Windows devices.

Make sure that you select the option to Add Python to PATH during installation (via the installer).

If you are on Linux, you can check if Python is already installed on your machine by typing python3 --version in a terminal. If it returns an error, you need to install it from your distribution's repository. On Ubuntu/Debian, this can be done by typing sudo apt install python3. Both pip (or pip3) and venv are distributed as separate packages on Ubuntu/Debian and can also be installed by typing sudo apt install python3-pip python3-venv.

Setup Visual Studio Code

First, head over to to code.visualstudio.com and grab the installer for your specific platform.

If you are on a Raspberry Pi (with Raspberry Pi OS), you can also install VS Code by simply typing sudo apt install code. On Linux distributions that support Snaps, you can do it by typing sudo snap install code --classic.

Once VS Code is installed, head over to the Extensions tab in the sidebar on the left by clicking on it or by pressing CTRL+SHIFT+X. Search for the 'Python' extension published by Microsoft and click on Install.

The Extensions tab in the left-hand sidebar.

Usage and Configuration

Now that you have finished setting up VS Code, you can go ahead and create a new Python file. Remember that the Python extension only works if you open a .py file or have selected the language mode for the active file as Python.

To change the language mode for the active file, simply press CTRL+K once and then press M after releasing the previous keys. This kind of keyboard shortcut is called a chord in VS Code. You can see more of them by pressing CTRL+K CTRL+S (another chord).

The Python extension in VS Code allows you to directly run a Python file by clicking on the 'Play' button on the top-right corner of the editor (without having to type python file.py in the terminal).

You can also do it by pressing CTRL+SHIFT+P to open the Command Palette and running the > Python: Run File in Terminal command.

Finally, you can configure VS Code's settings by going to File > Preferences > Settings or by pressing CTRL+COMMA. In VS Code, each individual setting has an unique identifier which you can see by clicking on the cog wheel that appears to the left of each setting and clicking on 'Copy Setting ID'. This ID is what will be referred to while talking about a specific setting. You can also search for this ID in the search bar under Settings.

Linting and Formatting Support (Optional)

Linters make it easier to find errors and check the quality of your code. On the other hand, code formatters help keep the source code of your application compliant with PEP (Python Enhancement Proposal) standards, which make it easier for other developers to read your code and collaborate with you.

For VS Code to provide linting support for your projects, you must first install a preferred linter like flake8 or pylint.

bash

pip install flake8

Then, go to Settings in VS Code and toggle the relevant setting (e.g. python.linting.flake8Enabled) for the Python extension depending on what you installed. You also need to make sure that python.linting.enabled is toggled on.

A similar process must be followed for code formatting. First, install something like autopep8 or black.

bash

pip install autopep8

You then need to tell VS Code which formatter to use by modifying python.formatting.provider and toggle on editor.formatOnSave so that it works without manual intervention.

If pip warns that the installed modules aren't in your PATH, you may have to specify the path to their location in VS Code (under Settings). Follow the method described under Working With Virtual Environments to do that.

Now, when you create a new Python file, VS Code automatically gives you a list of Problems (CTRL+SHIFT+M) in your program and formats the code on saving the file.

Identified problems in the source code, along with a description and line/column numbers.

You can also find the location of identified problems from the source overview on the right hand, inside the scrollbar.

Working With Virtual Environments

Virtual environments are a way of life for Python developers. Most Python projects require the installation of external packages and modules (via pip). Virtual environments allow you to separate one project's packages from your other projects, which may require a different version of those same packages. Hence, it allows all those projects to have the specific dependencies they require to work.

The Python extension makes it easier for you by automatically activating the desired virtual environment for the in-built terminal and Run Python File command after you set the path to the Python interpreter. By default, the path is set to use the system's Python installation (without a virtual environment).

To use a virtual environment for your project/workspace, you need to first make a new one by opening a terminal (View > Terminal) and typing python -m venv .venv. Then, you can set the default interpreter for that project by opening the Command Palette (CTRL+SHIFT+P) and selecting > Python: Select Interpreter.

You should now either close the terminal pane in VS Code and open a new one or type source .venv/bin/activate into the existing one to start using the virtual environment. Then, install the required packages for your project by typing pip install <package_name>.

VS Code, by default, looks for tools like linters and code formatters in the current Python environment. If you don't want to keep installing them over and over again for each new virtual environment you make (unless your project requires a specific version of that tool), you can specify the path to their location under Settings in VS Code. - flake8 - python.linting.flake8Path - autopep8 - python.formatting.autopep8Path

To find the global location of these packages on macOS and Linux, type which flake8 and which autopep8 in a terminal. If you are on Windows, you can use where <command_name>. Both these commands assume that flake8 and autopep8 are in your PATH.

Understanding Workspaces in VS Code

VS Code has a concept of Workspaces. Each 'project folder' (or the root/top folder) is treated as a separate workspace. This allows you to have project-specific settings and enable/disable certain extensions for that workspace. It is also what allows VS Code to quickly recover the UI state (e.g. files that were previously kept open) when you open that workspace again.

In VS Code, each workspace (or folder) has to be 'trusted' before certain features like linters, autocomplete suggestions and the in-built terminal are allowed to work.

In the context of Python projects, if you tend to keep your virtual environments outside the workspace (where VS Code is unable to detect it), you can use this feature to set the default path to the Python interpreter for that workspace. To do that, first Open a Folder (CTRL+K CTRL+O) and then go to File > Preferences > Settings > Workspace to modify python.defaultInterpreterPath.

Setting the default interpreter path for the workspace.

In VS Code settings you can search for settings by name using the bar at the top.

You can also use this approach to do things like use a different linter for that workspace or disable the code formatter for it. The workspace-specific settings you change are saved in a .vscode folder inside that workspace, which you can share with others.

If your VS Code is not recognizing libraries you are using in your code, double check the correct interpreter is being used. You can find which Python version you're using on the command line by running which python or which python3 on macOS/Linux, or where python or where python3 on Windows.

Working With Git in VS Code (Optional)

Using Version Control is required for developing applications. VS Code does have in-built support for Git but it is pretty barebones, not allowing much more than tracking changes that you have currently made and committing/pushing those changes once you are done.

For the best experience, it is recommended to use the GitLens extension. It lets you view your commit history, check who made the changes and much more. To set it up, you first need to have Git set up on your machine (go here) and then install GitLens from the Extensions tab in the sidebar on the left. You can now use those Git-related features by going to the Git tab in the sidebar (CTRL+SHIFT+G).

There are more Git-related extensions you could try as well, like Git History and GitLab Workflow. Give them a whirl too!

Community-driven & open source alternatives

While VS Code is open source (MIT-licensed), the distributed versions include some Microsoft-specific proprietary modifications, such as telemetry (app tracking). If you would like to avoid this, there is also a community-driven distribution of Visual Studio Code called VSCodium that provides freely-licensed binaries without telemetry.

Due to legal restrictions, VSCodium is unable to use the official Visual Studio Marketplace for extensions. Instead, it uses a separate vendor neutral, open source marketplace called Open VSX Registry. It doesn't have every extension, especially proprietary ones, and some are not kept up-to-date but both the Python and GitLens extensions are available on it.

You can also use the open source Jedi language server for the Python extension, rather than the bundled Pylance language server/extension, by configuring the python.languageServer setting. You can then completely disable Pylance by going to the Extensions tab. Note that, if you are on VSCodium, Jedi is used by default (as Pylance is not available on Open VSX Registry) when you install the Python extension.

Conclusion

Having the right tools and making sure they're set up correctly will greatly simplify your development process. While Visual Studio starts as a simple tool, it is flexible and extendable with plugins to suit your own preferred workflow. In this tutorial we've covered the basics of setting up your environment, and you should now be ready to start developing your own applications with Python!

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

PyQt6, PySide6, PyQt5 and PySide2 Books -- updated for 2022! — New editions extended and updated, now 780+ pages

2022-05-19T09:00:00+00:00

Hello! Today I have released new digital editions of my PyQt5, PyQt6, PySide2 and PySide6 book Create GUI Applications with Python & Qt.

This update adds over 200 pages of Qt examples and exercises - the book is now 780 pages long! - and continues to be updated and extended. The latest additions include:

Built-in dialogs, including QMessageBox and QFileDialog
Working with multiple windows, cross-window communication
Using QThreadPool.start() to execute Python functions
Long-running threads with QThread
Using custom widgets in Qt Designer
Recurring & single shot timers
Managing data files, working with paths
Packaging with PyInstaller on Windows, macOS & Linux
Creating distributable installers on Windows, macOS & Linux

This update marks the 5th Edition of the book.

As always, if you've previously bought a copy of the book you get these updates for free! Just go to the downloads page and enter the email you used for the purchase. If you have problems getting this update just get in touch.

Enjoy!

For an in-depth guide to building Python GUIs with PySide2 see my book, Create GUI Applications with Python & Qt5.

DiffCast: Hands-free Python Screencast Creator — Create reproducible programming screencasts without typos or edits

2022-01-26T11:00:00+00:00

Programming screencasts are a popular way to teach programming and demo tools. Typically people will open up their favorite editor and record themselves tapping away. But this has a few problems. A good setup for coding isn't necessarily a good setup for video -- with text too small, a window too big, or too many distractions. Typing code in live means mistakes, which means more time editing or confusion for the people watching.

DiffCast eliminates that, automatically generating screencasts from Python source files you prepare ahead of time.

DiffCast is written in Python with PyQt6. Source code available on Github

Given the following Python source files:

demo1.py
demo2.py
demo3.py
demo4.py

python
print('Hello, world!')

python
name = input('What is your name?\n')
print(f'Hello, {name}!')

python
friends = ['Emelia', 'Jack', 'Bernardina', 'Jaap']

name = input('What is your name?\n')

if name in friends:
    print(f'Hello, {name}!')
else:
    print("I don't know you.")

python
friends = ['Emelia', 'Jack', 'Bernardina', 'Jaap']

while True:
    name = input('What is your name?\n')

    if name in friends:
        print(f'Hello, {name}!')
    else:
        print("I don't know you.")
        friends.append(name)

DiffCast will generate the following screencast (editor can be captured separately).

The editor view is configured to be easily readable in video, without messing with your IDE settings. Edits happen at a regular speed, without mistakes, making them easy to follow. Each diffcast is completely reproducible, with the same files producing the same output every time. You can set defined window sizes, or remove the titlebar to record.

Designed for creating reproducible tutoring examples, library demos or demonstrating code to a class. You can also step forwards and backwards through each file manually, using the control panel.

Finally, you can write out edits to a another file, and show the file location in a file listing for context. Run the intermediate files to demonstrate the effect of the changes.

DiffCast is open source (GPL licensed) & free to use. For bug reports, feature requests see the Github project.

For an in-depth guide to building Python GUIs with PyQt6 see my book, Create GUI Applications with Python & Qt6.

PySide6 tutorial now available — Complete course, updated for PySide2 & PySide6

2021-05-14T07:00:00+00:00

Hello! With the release of Qt6 versions of PyQt and PySide the course was getting a little crowded. So, today I've split the PySide tutorials into their own standalone PySide2 course and PySide6 course.

The tutorials have all been updated for PySide2 & PySide6, with some additional improvements based on the latest editions of the book.

This first update includes the following PySide tutorials --

Getting started creating Python GUIs with PySide

Creating your first app with PySide A simple Hello World! application with Python and Qt.
Signals, Slots & Events Triggering actions in response to user behaviors and GUI events.
Widgets Using PySide's built-in widgets to build your applications.
Layout management Use layouts to effortlessly position widgets within the window.
Actions — Toolbars & Menus Defining toolbars, menus and keyboard shortcuts with QAction.
Dialogs and Alerts Notify your users and ask for their input.

Using Qt Designer with PySide

First steps with Qt Designer Use Qt Designer's drag and drop interface to design your GUI.
Laying Out Your GUIs With Qt Designer Use Qt Designer to effortlessly build your application UI.
Embedding custom widgets from Qt Designer Learn how to use custom widgets in your PySide applications when designing with Qt Designer.
Creating Dialogs With Qt Designer Using the drag and drop editor to build PySide dialogs.
The QResource System Using the QResource system to package additional data with your applications.

Extended UI features in PySide

System tray & Mac menu bar applications Add quick access functions to your apps.
Add scrollable regions with QScrollArea Run out of space in your GUI? Add a scrollable region to your application.
Creating searchable widget dashboards Make dashboard UIs easier to use with widget search & text prediction.
Transmitting extra data with Qt Signals Modifying widget signals to pass contextual information to slots.
Creating additional windows Opening new windows for your application.

Multi threading PySide applications & QProcess

Multithreading PySide applications with QThreadPool Run background tasks concurrently without impacting your UI.
Using QProcess to run external programs Run background programs without impacting your UI.

Qt Model Views

The ModelView Architecture Qt's MVC-like interface for displaying data in views.
Displaying tabular data in ModelViews Create customized table views with conditional formatting, numpy and pandas data sources.

Pyside plotting & graphics with Matplotlib/PyQtGraph

Plotting with PyQtGraph Create custom plots in PySide with PyQtGraph.
Plotting with Matplotlib Create PySide plots with the popular Python plotting library.

Bitmap graphics and custom widgets

QPainter and Bitmap Graphics Introduction to the core features of QPainter.
Creating custom GUI widgets in PySide Build a completely functional custom widget from scratch using QPainter.

Packaging (PySide2 only)

Packaging PySide2 applications for Windows, with PyInstaller Turn your Qt5 application into a distributable installer for Windows.
Packaging PySide apps with fbs Distribute cross-platform GUI applications with the fman Build System.

That's all for now!

You can also still access the PyQt5 tutorial and PyQt6 tutorial.

For an in-depth guide to building Python GUIs with PySide2 see my book, Create GUI Applications with Python & Qt5.

PyQt6 Book now available: Create GUI Applications with Python & Qt6 — The hands-on guide to making apps with Python

2021-04-09T15:00:00+00:00

Hello! Today I have released the first PyQt6 edition of my book Create GUI Applications, with Python & Qt6.

This update follows the 4th Edition of the PyQt5 book updating all the code examples and adding additional PyQt6-specific detail. The book contains 600+ pages and 200+ complete code examples taking you from the basics of creating PyQt applications to fully functional apps.

Enjoy!

For an in-depth guide to building Python GUIs with PyQt5 see my book, Create GUI Applications with Python & Qt5.

PySide6 Book now available: Create GUI Applications with Python & Qt6 — The hands-on guide to making apps with Python

2021-03-15T07:00:00+00:00

Hello! This morning I released the first Qt6 edition of my PySide book Create GUI Applications, with Python & Qt6.

This update follows the 4th Edition of the PySide2 book updating all the code examples and adding additional PySide6-specific detail. The book contains 600+ pages and 200+ complete code examples taking you from the basics of creating PySide applications to fully functional apps.

If you have any questions or difficulty getting hold of this update, just get in touch.

Enjoy!

For an in-depth guide to building Python GUIs with PySide6 see my book, Create GUI Applications with Python & Qt6.

Using MicroPython and uploading libraries on Raspberry Pi Pico — Using rshell to upload custom code

2021-02-22T08:00:00+00:00

MicroPython is an implementation of the Python 3 programming language, optimized to run microcontrollers. It's one of the options available for programming your Raspberry Pi Pico and a nice friendly way to get started with microcontrollers.

MicroPython can be installed easily on your Pico, by following the instructions on the Raspberry Pi website (click the Getting Started with MicroPython tab and follow the instructions).

After that point you might get a bit stuck. The Pico documentation covers connecting to the Pico from a Pi, so if you're wanting to code from your own computer you'll need something else. One option is the Thonny IDE which you use to write and upload code to your Pico. It's got a nice friendly interface for working with Python.

But if you don't want to change your IDE, or want a way to communicate with your Pico from the command line? You're in luck: there is a simple tool for accessing the MicroPython REPL on your Pico and uploading custom Python scripts or libraries you may wish to use: rshell

In this tutorial I'll take you through working with MicroPython in rshell, coding live and uploading custom scripts to your Pico.

Installing rshell

Rshell itself is built on Python (not MicroPython) and can be installed and run locally on your main machine. You can install it like any other Python library.

bash

python -m pip install rshell

Unfortunately, the current version of rshell does not always play nicely with the Raspberry Pico. If you have problems you can install a fixed version in the pico branch from the rshell repository. You can install this directly from Github with the following --

bash

python -m pip install https://github.com/dhylands/rshell/archive/pico.zip

This will download the latest version of the pico branch (as a .zip) and install this in your Python environment.

Once installed, you will have access to a new command line tool rshell.

The rshell interface

To use rshell from the command line, enter rshell at your command prompt. You will see a welcome message and the prompt will turn green, to indicate you're in rshell mode.

The rshell interface on Windows 10

The rshell interface on macOS

If previous pip install worked but the rshell command doesn't work, then you may have a problem with your Python paths.

To see the commands available in rshell, enter help and press Enter.

python

help

Documented commands (type help <topic>):
========================================
args    cat  connect  date  edit  filesize  help  mkdir  rm     shell
boards  cd   cp       echo  exit  filetype  ls    repl   rsync

Use the exit command to exit rshell.

You can exit rshell at any time by entering exit or pressing Ctrl-C. Once exited the prompt will turn white.

The basic file operation commands are shown below.

cd <dirname> change directory
cp <from> <to> copy a file
ls list current directory
rm <filename> remove (delete) a file
filesize <filename> give the size of a file in bytes

If you type ls and press enter you will see a listing of your current folder on your host computer. The same goes for any of the other file operations, until we've connect a board and opened it's file storage -- so be careful! We'll look at how to connect to a MicroPython board and work with the files on it next.

Connecting to your Pico with rshell

Enter boards to see a list of MicroPython boards connected to your computer. If you don't have any connected boards, you'll see the message No boards connected.

If your board isn't connected plug your Pico in now. You can use the connect command to connect to the board, but for that you'll need to know which port it is on. Save yourself some effort and just restart rshell to connect automatically. To do this, type exit and press Enter (or press Ctrl-C) to exit and then restart rshell by entering rshell again at the prompt.

If a board is connected when you start rshell you will see something like the following...

python

C:\Users\Gebruiker>rshell
Connecting to COM4 (buffer-size 128)...
Trying to connect to REPL  connected

Or an equivalent on macOS...

python

Martins-Mac: ~ mfitzp$ rshell
Connecting to /dev/cu.usbmodem0000000000001 (buffer-size 128)
Trying to connect to REPL  connected

...which shows you've connected to the MicroPython REPL on the Raspberry Pi Pico. Once connected the boards command will return some information about the connected board, like the following.

python

pyboard @ COM4 connected Epoch: 1970 Dirs:

The name on the left is the type of board (Pico appears as pyboard) and connected port (here COM4). The label at the end Dirs: will list any files on the Pico -- currently none.

Starting a REPL

With the board connected, you can enter the Pico's REPL by entering the repl command. This will return something like the following

python

repl
Entering REPL. Use Control-X to exit.
>
MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040
Type "help()" for more information.
>>>
>>>

You are now writing Python on the Pico! Try entering print("Hello!") at the REPL prompt.

python

MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040
Type "help()" for more information.
>>>
>>> print("Hello!")
Hello!

As you can see, MicroPython works just like normal Python. If you enter help() and press Enter, you'll get some basic help information about MicroPython on the Pico. Helpfully, you also get a small reference to how the pins on the Pico are numbered and the different ways you have to control them.

python

Type "help()" for more information.
>>> help()
Welcome to MicroPython!

For online help please visit https://micropython.org/help/.

For access to the hardware use the 'machine' module.  RP2 specific commands
are in the 'rp2' module.

Quick overview of some objects:
  machine.Pin(pin) -- get a pin, eg machine.Pin(0)
  machine.Pin(pin, m, [p]) -- get a pin and configure it for IO mode m, pull mode p
    methods: init(..), value([v]), high(), low(), irq(handler)
  machine.ADC(pin) -- make an analog object from a pin
    methods: read_u16()
  machine.PWM(pin) -- make a PWM object from a pin
    methods: deinit(), freq([f]), duty_u16([d]), duty_ns([d])
  machine.I2C(id) -- create an I2C object (id=0,1)
    methods: readfrom(addr, buf, stop=True), writeto(addr, buf, stop=True)
             readfrom_mem(addr, memaddr, arg), writeto_mem(addr, memaddr, arg)
  machine.SPI(id, baudrate=1000000) -- create an SPI object (id=0,1)
    methods: read(nbytes, write=0x00), write(buf), write_readinto(wr_buf, rd_buf)
  machine.Timer(freq, callback) -- create a software timer object
    eg: machine.Timer(freq=1, callback=lambda t:print(t))

Pins are numbered 0-29, and 26-29 have ADC capabilities
Pin IO modes are: Pin.IN, Pin.OUT, Pin.ALT
Pin pull modes are: Pin.PULL_UP, Pin.PULL_DOWN

Useful control commands:
  CTRL-C -- interrupt a running program
  CTRL-D -- on a blank line, do a soft reset of the board
  CTRL-E -- on a blank line, enter paste mode

For further help on a specific object, type help(obj)
For a list of available modules, type help('modules')

You can run help() in the REPL any time you need a reminder.

While we're here, lets flash the LED on the Pico board.

Enter the following at the REPL prompt...

python

from machine import Pin
led = Pin(25, Pin.OUT)

led.toggle()

Every time you call led.toggle() the LED will toggle from ON to OFF or OFF to ON.

To exit the REPL at any time press Ctrl-X

Uploading a file

MicroPython comes with a lot of built-in support for simple devices and communication protocols -- enough to build some quite fun things just by hacking in the REPL. But there are also a lot of libraries available for working with more complex hardware. To use these, you need to be able to upload them to your Pico! Once you can upload files, you can also edit your own code locally on your own computer and upload it from there.

To keep things simple, lets create our own "library" that adjusts the brightness of the LED on the Pico board -- exciting I know. This library contains a single function ledon which accepts a single parameter brightness between 0 and 65535.

python

from machine import Pin, PWM

led = PWM(Pin(25))

def ledon(brightness=65535):
    led.duty_u16(brightness)

Don't worry if you don't understand it, we'll cover how this works later. The important bit now is getting this on your Pico.

Take the code above and save it in a file named picoled.py on your main computer, in the same folder you're executing rshell from. We'll upload this file to the Pico next.

Start rshell if you are not already in it -- look for the green prompt. Enter boards at the prompt to get a list of connected boards.

bash

pyboard @ COM4 connected Epoch: 1970 Dirs:

To see the directory contents of the pyboard device, you can enter:

bash

ls /pyboard

You should see nothing listed. The path /pyboard works like a virtual folder meaning you can copy files to this location to have the uploaded to your Pico. It is only available by a pyboard is connected. To upload a file, we copy it to this location. Enter the following at the prompt.

bash

cp picoled.py /pyboard/picoled.py

After you press Enter you'll see a message confirming the copy is taking place

python

C:\Users\Gebruiker> cp picoled.py /pyboard
Copying 'C:\Users\Gebruiker/picoled.py' to '/pyboard/picoled.py' ...

Once the copy is complete, run boards again at the prompt and you'll see the file listed after the Dirs: section, showing that it's on the board.

bash

C:\Users\Gebruiker> boards
pyboard @ COM4 connected Epoch: 1970 Dirs: /picoled.py /pyboard/picoled.py

You can also enter ls /pyboard to see the listing directly.

bash

C:\Users\Gebruiker> ls /pyboard
picoled.py

If you ever need to upload multiple files, just repeat the upload steps until everything is where it needs to be. You can always drop in and out of the REPL to make sure things work.

Using uploaded libraries

Now we've uploaded our library, we can use it from the REPL. To get to the MicroPython REPL enter the repl command in rshell as before. To use the library we uploaded, we can import it, just like any other Python library.

python

MicroPython v1.14 on 2021-02-14; Raspberry Pi Pico with RP2040
Type "help()" for more information.
>>>
>>> import picoled
>>> picoled.ledon(65535)
>>> picoled.ledon(30000)
>>> picoled.ledon(20000)
>>> picoled.ledon(10000)

Or to pulse the brightness of the LED...

python

>>> import picoled
>>> import time
>>> while True:
...     for a in range(0, 65536, 10000):
...         picoled.ledon(a)
...         time.sleep(0.1)

Auto-running Python

So far we've been uploading code and running it manually, but once you start building projects you'll want your code to run automatically.

When it starts, MicroPython runs two scripts by default: boot.py and main.py, in that order. By uploading your own script with the name main.py it will run automatically every time the Raspberry Pico starts.

Let's update our "library" to become an auto script that runs at startup. Save the following code to a script named main.py.

python

from machine import Pin, PWM
from time import sleep

led = PWM(Pin(25))

def ledon(brightness=65535):
    led.duty_u16(brightness)


while True:
    for a in range(0, 65536, 10000):
        ledon(a)
        sleep(0.1)

In rshell run the command to copy the file to main.py on the board.

bash

cp main.py /pyboard/main.py

Don't copy this file to boot.py -- the loop will block the REPL startup and you won't be able to connect to your Pico to delete it again! If you do this, use the Resetting Flash memory instructions to clear your Pico. You will need to re-install MicroPython afterwards.

Once the main.py file is uploaded, restart your Pico -- either unplug and re-plug it, or press Ctrl-D in the REPL -- and the LED will start pulsing automatically. The script will continue running until it finishes, or the Pico is reset. You can replace the main.py script at any time to change the behavior, or delete it with.

bash

rm /pyboard/main.py

What's next?

Now you can upload libraries to your Pico you can get experimenting with the many MicroPython libraries that are available.

If you're looking for some more things to do with MicroPython on your Pico, there are some MicroPython examples available from Raspberry Pi themselves, and also the MicroPython documentation for language/API references.

Writing a SAM Coupé SCREEN$ Converter in Python — Interrupt optimizing image converter

2021-01-28T14:00:00+00:00

The SAM Coupé was a British 8 bit home computer that was pitched as a successor to the ZX Spectrum, featuring improved graphics and sound and higher processor speed.

The SAM Coupé's high-color MODE4 could manage 256x192 resolution graphics, with 16 colors from a choice of 128. Each pixel can be set individually, rather than using PEN/PAPER attributes as on the Spectrum. But there's more. The SAM also supports line interrupts which allow palette entries to be changed on particular scan lines: a single palette entry can display multiple colors.

The limitation that color can only be changed per line means it's not really useful for games, or other moving graphics. But it does allow you to use a completely separate palette for "off screen" elements like panels. For static images, such as photos, it's more useful - assuming that the distribution of color in the image is favorable¹.

Demonstration SCREEN$ were a regular feature of SAM Coupé disk magazines, but interrupts were rarely used since the placement had to be done manually. Now we're living in the future, I wanted to have a crack at automating line interrupts to squeeze out as many colors as possible & let the SAM show off it's capabilities.

If you just want the converter, you can get it here. It is written in Python, using Pillow for image color conversion.

First a quick look at the SAM Coupé screen modes to see what we're dealing with.

Sam Coupe Screen Modes

There are 4 screen modes on the SAM Coupé.

MODE 1 is the ZX Spectrum compatible mode, with 8x8 blocks which can contain 2 colors PAPER (background) and PEN (foreground). The framebuffer in MODE 1 is non-linear, in that line 1 is followed by line 8.
MODE 2 also uses attributes, with PAPER and PEN, but the cells are 8x1 pixels and the framebuffer is linear. This MODE wasn't used a great deal, but was the fastest mode on the SAM due to Spectrum-compatibility delays in MODE 1.
MODE 3 is high resolution, with double the X pixels but only 4 colours -- making it good for reading text.
MODE 4 is the high color mode, with 256x192 and independent coloring of every pixel from a palette of 16. Most games/software used this mode.

Mode	Dimensions	Framebuffer	bpp	Colors	Size	Notes
4	256×192	linear	4	16	24 KB	High color
3	512×192	linear	2	4	24 KB	High resolution
2	256×192	linear	1	16	12 KB	Color attributes for each 8x1 block
1	256×192	non-linear	1	16	6.75KB	Color attributes for each 8×8 block; matches ZX Spectrum

Most SAM Coupe SCREEN$ were in MODE 4, so that's what we'll be targeting. It would be relatively easy to support MODE 3 on top of this².

The SCREEN$ format

The format itself is fairly simple, consisting of the following bytes.

Bytes	Content
24576	Pixel data, Mode 4 4bpp: 1 byte=2 pixels; Mode 3 2bpp: 1 byte = 4 pixels
16	Mode 4 Palette A
4	Mode 3 Palette A store
16	Mode 4 Palette B
4	Mode 3 Palette B store
Variable	Line interrupts 4 bytes per interrupt (see below)
1	FF termination byte

In MODE 4 the pixel data is 4bbp, that is 1 byte = 2 pixels (16 possible colors). To handle this we can create our image as 16 colors and bit-shift the values before packing adjacent pixels into a single byte.

Palette A & B

As shown in the table above the SAM actually supports two simultaneous palettes (here marked A & B). These are full palettes which are alternated between, by default 3 times per second, to create flashing effects. The entire palette is switched, but you can opt to only change a single color. The rate of flashing is configurable with:

basic

POKE &5A08, <value>

The <value> is the time between swaps of alternate palettes, in 50ths of a second. This is only generally useful for creating flashing cursor effects ³. For converting to SAM SCREEN$ we'll be ignoring this and just duplicating the palette.

The exporter supports palette flash for GIF export.

MODE 3 Store

When switching between MODE 3 and MODE 4. The palettes of MODE 3 & 4 are separate, but palette operations on the same CLUT. When changing mode 4 colors are aside to a temporary store, and replaced when switching back. These values are also saved when saving SCREEN$ files (see "store" entries above), so you can replace the MODE 3 palette by loading a MODE 4 screen. It's a bit odd.

We can ignore this for our conversions and just write a default set of bytes.

Interrupts

Interrupts define locations on the screen where a given palette entry (0-15) changes to a different color from the 128 color system palette. They are encoded with 4 bytes per interrupt, with multiple interrupts appended one after another.

Bytes	Content
1	Y position, stored as 172-y (see below)
1	Color to change
1	Palette A
1	Palette B

Interrupt coordinates set from BASIC are calculated from -18 up to 172 at the top of the screen. The plot range in BASIC is actually 0..173, but interrupts can't affect the first pixel (which makes sense, since this is handled through the main palette).

When stored in the file, line interrupts are stored as 172-y. For example, a line interrupt at 150 is stored in the file as 22. The line interrupt nearest the top of the screen (1st row down, interrupt position 173) would be stored as 172-172=0.

This sounds complicated, but actually means that to get our interrupt Y byte we can just subtract 1 from the Y coordinate in the image.

Converting Image to SCREEN$

We now have all the information we need to convert an image into a SCREEN$ format. The tricky bit (and what takes most of the work) is optimising the placement of the interrupts to maximise the number of colors in the image.

Pre-processing

Processing is done using Pillow package for Python. Input images are resized and cropped to fit, using using the ImageOps.fit() method, with centering.

python

SAM_COUPE_MODE4 = (256, 192, 16)
WIDTH, HEIGHT, MAX_COLORS = SAM_COUPE_MODE4

im = Image.open(fn)

# Resize with crop to fit.
im = ImageOps.fit(im, (WIDTH, HEIGHT), Image.ANTIALIAS, 0, (0.5, 0.5))

If the above crop is bad, you can adjust it by pre-cropping/sizing the image beforehand. There isn't the option to shrink without cropping as any border area would waste a palette entry to fill the blank space.

Interrupts

This is the bulk of the process for generating optimized images: the optimize method is shown below -- this shows the high level steps taken to reach optimal number of colors using interrupts to compress colors.

python

def optimize(im, max_colors, total_n_colors):
    """
    Attempts to optimize the number of colors in the screen using interrupts. The
    result is a dictionary of color regions, keyed by color number
    """
    optimal_n_colors = max_colors
    optimal_color_regions = {}
    optimal_total_interrupts = 0

    for n_colors in range(max_colors, total_n_colors+1):
        # Identify color regions.
        color_regions = calculate_color_regions(im, n_colors)

        # Compress non-overlapping colors together.
        color_regions = compress_non_overlapping(color_regions)

        # Simplify our color regions.
        color_regions = simplify(color_regions)

        total_colors = len(color_regions)

        # Calculate home many interrupts we're using, length drop initial.
        _, interrupts = split_initial_colors(color_regions)
        total_interrupts = n_interrupts(interrupts)

        print("- trying %d colors, with interrupts uses %d colors & %d interrupts" % (n_colors, total_colors, total_interrupts))

        if total_colors <= max_colors and total_interrupts <= MAX_INTERRUPTS:
            optimal_n_colors = n_colors
            optimal_color_regions = color_regions
            optimal_total_interrupts = total_interrupts
            continue
        break

    print("Optimized to %d colors with %d interrupts (using %d palette slots)" % (optimal_n_colors, optimal_total_interrupts, len(optimal_color_regions)))
    return optimal_n_colors, optimal_color_regions

The method accepts the image to compress, a max_colors argument, which is the number of colors supported by the screen mode (16). This is a lower bound, the minimum number of colors we should be able to get in the image. The argument total_n_colors contains the total number of colors in the image, capped at 128 -- the number of colors in the SAM palette. This is the upper bound, the maximum number of colors we can use. If the total_n_colors < 16 we'll skip optimization.

Each optimization round is as follows -

calculate_color_regions generates a dictionary of color regions in the image. Each region is a (start, end) tuple of y positions in the image where a particular color is found. Each color will usually have many blocks.
compress_non_overlapping takes colors with few blocks and tries to combine them with other colors with no overlapping regions: transitions between colors will be handled by interrupts
simplify takes the resulting color regions and tries to simplify them further, grouping blocks back with their own colors if they can and then combining adjacent blocks
total_colors the length of the color_regions is now the number of colors used
split_initial_colors removes the first block, to get total number of interrupts

The compress_non_overlapping algorithm makes no effort to find the best compression of regions - I experimented with this a bit and it just explodes the number of interrupts for little real gain in image quality.

The optimization process is brute force - step forward, increase the number of colors by 1 and perform the optimization steps above. If the number of colors > 16 we've gone too far: we return the last successful result, with colors <= 16.

SAM Coupé Palette

Once we have the colors for the image we map the image over to the SAM Coupé palette. Every pixel in the image must have a value between 0-15 -- pixels for colors controlled by interrupts are mapped to their "parent" color. Finally, all the colors are mapped across from their RGB values to the nearest SAM palette number equivalent.

This is sub-optimal, since the choice of colors should really be informed by the colors available. But I couldn't find a way to get Pillow to quantize to a fixed palette without dithering.

The mapping is done by calculating the distance in RGB space for each color to each color in the SAM 128 color palette, using the usual RGB color distance algorithm.

python

def convert_image_to_sam_palette(image, colors=16):
    new_palette = []
    rgb = image.getpalette()[:colors*3]
    for r, g, b in zip(rgb[::3], rgb[1::3], rgb[2::3]):

        def distance_to_color(o):
            return distance(o, (r, g, b))

        spalette = sorted(SAM_PALETTE, key=distance_to_color)
        new_palette.append(spalette[0])

    palette = [c for i in new_palette for c in i]
    image.putpalette(palette)
    return image

Packing bits

Now our image contains pixels of values 0-15 we can pack the bits and export the data. we can iterate through the flattened data in steps of 2, and pack into a single byte:

python

pixels = np.array(image16)

image_data = []
pixel_data = pixels.flatten()
# Generate bytestream and palette; pack to 2 pixels/byte.
for a, b in zip(pixel_data[::2], pixel_data[1::2]):
    byte = (a << 4) | b
    image_data.append(byte)

image_data = bytearray(image_data)

The operation a << 4 shifts the bits of integer a left by 4, so 15 (00001111) becomes 240 (11110000), while | ORs the result with b. If a = 0100 and b = 0011 the result would be 01000011 with both values packed into a single byte.

Writing the SCREEN$

Finally, the image data is written out, along with the palette data and line interrupts.

python

        # Additional 4 bytes 0, 17, 34, 127; mode 3 temporary store.
        bytes4 = b'\x00\x11\x22\x7F'

        with open(outfile, 'wb') as f:
            f.write(image_data)
            # Write palette.
            f.write(palette)

            # Write extra bytes (4 bytes, 2nd palette, 4 bytes)
            f.write(bytes4)
            f.write(palette)
            f.write(bytes4)

            # Write line interrupts
            f.write(interrupts)

            # Write final byte.
            f.write(b'\xff')

To actually view the result, I recommend the SAM Coupé Advanced Disk Manager.

You can see the source code for the img2sam converter on Github.

Examples

Below are some example images, converted from PNG/JPG source images to SAM Coupé MODE 4 SCREEN$ and then back into PNGs for display. The palette of each image is restricted to the SAM Coupé's 128 colors and colors are modified using interrupts.

Pool 16 colors, no interrupts

Pool 24 colors, 12 interrupts (compare gradients)

This image pair shows the effect on line interrupts on a image without dither. The separation between the differently colored pool balls makes this a good candidate.

Leia 26 colors, 15 interrupts

Tully 22 colors, 15 interrupts

The separation between the helmet (blue, yellow components) and horizontal line in the background make this work out nicely. Same for the second image of Tully below.

Isla 18 colors, 6 interrupts

Tully (2) 18 colors, 5 interrupts

Dana 17 colors, 2 interrupts

Lots of images that don't compress well because the same shades are used throughout the image. This is made worse by the conversion to the SAM's limited palette of 128.

Interstellar 17 colors, 3 interrupts

Blade Runner 16 colors (11 used), 18 interrupts

This last image doesn't manage to squeeze more than 16 colors out of the image, but does reduce the number of colors used for those 16 to just 11. This gives you 5 spare colors to add something else to the image.

Converting SCREEN$ to Image

Included in the scrimage package is the sam2img converter, which will take a SAM MODE4 SCREEN$ and convert it to an image. The conversion process respects interrupts and when exporting to GIF will export flashing palettes as animations.

The images above were all created using sam2img on SCREEN$ created with img2sam. The following two GIFs are examples of export from SAM Coupe SCREEN$ with flashing palettes.

Flashing palette

Flashing palette and flashing Line interrupts

You can see the source code for the sam2img converter on Github.

An ideal image either has gradients down the image, or regions of isolated non-overlapping color. But it's hard to predict as conversion to the SAM palette can run some colors together. ↩
I experimented a bit with converting to MODE 3, but only 4 colors meant not very exciting results. ↩
With faster flash speeds (1 50th/second) you can use it to sort of merge nearby colors to create additional shades, while giving yourself a headache. ↩

Squeezing Space Invaders onto the BBC micro:bit's 25 pixels — MicroPython retro game in just 25 pixels

2021-01-21T07:00:00+00:00

How much game can you fit into 25 pixels? Quite a bit it turns out.

This is a mini clone of arcade classic Space Invaders for the BBC micro:bit microcomputer. Using the accelerometer and two buttons for input, to can beat off wave after wave of aliens that advance towards you.

The screen limits the detail we can manage: each sprite takes up a single pixel on the screen. The aliens don't drop bombs, as you'd have only 1-2 pixels to react. The buildings/defences at the bottom are missing, as they'd serve no purpose without the bombs. But it's still a lot of fun!

The aliens advance down the screen when they reach the edge. Some waves cover the entire width of the screen and will move down straight away -- shoot the edges to slow them down.

The controls are as follows --

Tilt left/right to control your fighter, tilt further to move faster.
Button A - shoot gun
Button B - fire thermonuclear bomb

Bomb? Yes! In this version you get a big bomb to save yourself when things get tricky. The blast wipes out 50% of the aliens currently on screen, but leaves you blinded for a couple of moves. Use wisely!

The game is written in MicroPython. If you have a BBC micro:bit just copy and paste the code into the Python web editor and then flash it to your device.

python

from microbit import *
import random

MIN_COORD, MAX_COORD = 0, 4  # Range of valid coordinates for the display.
MAX_MISSILES = 5             # Number of missiles player can have on screen at once.
DIFFICULTY_INCREASE = 0.25   # Increase in difficulty between waves.

ALIEN_START_POSITIONS = [
    # Each row is a unique start pattern, defined as tuples of x,y coordinates.
    [(1, 0), (2, 0), (3, 0), (1, 1), (2, 1), (3, 1)],
    [(0, 0), (1, 0), (2, 0), (3, 0), (4, 0), (2, 1)],
    [(1, 0), (2, 0), (3, 0), (0, 1), (2, 1), (4, 1)],
    [(1, 0), (2, 0), (3, 0), (1, 1), (3, 1), (2, 2)],
]

def wait_for_button():
    # Wait for either button to be pressed.
    while not (button_a.was_pressed() or button_b.was_pressed()):
        sleep(1)

def move(sprite, x, y):
    """
    Move the given sprite by the given x & y amounts.
    """
    return sprite[0] + x, sprite[1] + y

def in_bounds(pos):
    """
    Return True if the position is within the valid screen coordinates.
    """
    if pos[0] < MIN_COORD or pos[0] > MAX_COORD:
        return False
    if pos[1] < MIN_COORD or pos[1] > MAX_COORD:
        return False
    return True


class Game:
    """
    Game class holds the current game state.
    """

    def reset(self):
        # Initial values
        self.x = 2  # Player x coordinate start (middle).
        self.xf = 2.0  # x coordinate float, allows us to use tilt for move speed.

        self.missiles = []  # Active missles on screen.
        self.aliens = []    # Active aliens on screen.
        self.alien_velocity_x = 1  # Horizontal speed of aliens.

        self.bombs = 3        # Number of bombs the player has.
        self.active_bomb = 0  # Countdown timer for the current active bomb.

        self.score = 0        # Player score.

        self.tick = 0         # Game loop tick.
        self.level = 0        # Current game level.
        self.difficulty = 20  # Is in reverse, decrement to increase.


    def handle_input(self):
        self.tick += 1
        acc_x = accelerometer.get_x()

        # Use the accelerometer / 512 so the player can move x at speed by tilting more.
        if acc_x < 0:
            self.xf += acc_x / 512
        if acc_x > 0:
            self.xf += acc_x / 512

        # Constrain to the screen dimensions.
        if self.xf > MAX_COORD:
            self.xf = MAX_COORD

        if self.xf < MIN_COORD:
            self.xf = MIN_COORD

        self.x = int(self.xf)

        if button_a.was_pressed():
            # Add missile, at players current x position.
            self.missiles.append((self.x, 4))

        if button_b.was_pressed() and self.bombs:
            # Fire bomb. Flash + remove half the aliens.
            # randint(0,1) will be 50% 1, 50% 0 ..if 0 (False) alien will be skipped.
            self.aliens = [alien for alien in self.aliens if random.randint(0,1)]
            self.active_bomb = 3 # Reduces 1 per tick. Screen at 3 * bright.
            self.bombs -= 1

    def add_aliens(self):
        # We need to copy, or we'll me modifying the original lists.
        alien_position = self.level % len(ALIEN_START_POSITIONS)
        self.aliens = ALIEN_START_POSITIONS[alien_position].copy()
        self.tick = 0

    def advance_aliens(self):
        """
        If aliens have reached the screen edge, advance them all downwards.
        """
        for alien in self.aliens:
            if (
                (self.alien_velocity_x == -1 and alien[0] == MIN_COORD) or
                (self.alien_velocity_x == +1 and alien[0] == MAX_COORD)
            ):
                # If any aliens are at the far edge, increment y, and reverse.
                self.alien_velocity_x = -self.alien_velocity_x
                self.aliens = [move(alien, 0, 1) for alien in self.aliens]
                # This can happen if detached alien slips past bottom.
                self.aliens = [alien for alien in self.aliens if in_bounds(alien)]
                return True  # No other move this time.

    def aliens_can_move(self):
        if self.tick > self.difficulty:
            self.tick = 0
            return True

    def move_aliens(self):
        # Move aliens horizontally.
        self.aliens = [move(alien, self.alien_velocity_x, 0) for alien in self.aliens]

    def move_missiles(self):
        # Advance positions of missiles (upwards)
        self.missiles = [move(missile, 0, -1) for missile in self.missiles]
        self.missiles = [missile for missile in self.missiles if in_bounds(missile)]

    def check_collisions(self):
        for missile in self.missiles[:]:  # Iterate a copy.
            if missile in self.aliens:
                # Since we store by coordinates, we can remove using the missile coords.
                self.aliens.remove(missile)
                self.missiles.remove(missile)
                self.score += 1

        if not self.aliens:
            # Wave complete? Increase difficulty (decrement) and add new aliens.
            self.difficulty -= DIFFICULTY_INCREASE
            self.level += 1
            self.bombs += 1
            self.add_aliens()

    def draw(self):
        display.clear()

        if self.active_bomb:
            # Bomb is drawn as an overlay of gradually decaying light.
            for dx in range(MAX_COORD + 1):
                for dy in range(MAX_COORD + 1):
                    display.set_pixel(dx, dy, self.active_bomb * 3)

            # Decrement so next draw is fainter.
            self.active_bomb -= 1

        # Draw all the aliens.
        for pos in self.aliens:
            display.set_pixel(pos[0], pos[1], 9)

        # Draw all the current player missles.
        for pos in self.missiles:
            display.set_pixel(pos[0], pos[1], 5)

        # Draw the players spaceship.
        display.set_pixel(self.x, 4, 9)

    def game_over(self):
        return (self.x, 4) in self.aliens



game = Game() # Create our game object.


while True:

    display.show(Image.TARGET)
    wait_for_button()

    game.reset() # Reset the game state.
    game.add_aliens()

    # Main loop
    while not game.game_over():
        game.handle_input()
        if game.aliens_can_move():
            if not game.advance_aliens():
                game.move_aliens()
        game.move_missiles()
        game.draw()
        game.check_collisions()

        sleep(100)

    display.show(Image.ANGRY)
    sleep(1000)
    display.scroll(game.score)

You can adjust the difficulty by adjusting the difficulty setting, or speed. You could also modify the bomb to only destroy 33% of aliens, or less, to make it less of a certain life-saver.

The video below shows a short playthrough and end of game score.

Have fun!

Etch-A-Snap — The Raspberry Pi powered Etch-A-Sketch camera

2019-04-07T15:20:00+00:00

Etch-A-Snap is (probably) the worlds first Etch-A-Sketch Camera. Powered by a Raspberry Pi Zero (or Zero W) it snaps photos just like any other camera, but outputs them by drawing to an Pocket Etch-A-Sketch screen. Quite slowly.

Photos are processed down to 240x144 pixel 1-bit (black & white) line drawings using Pillow and OpenCV and then translated into plotter commands by building a network graph representation with networkx. The Etch-A-Sketch wheels are driven by two 5V stepper motors mounted into a custom 3D printed frame. The Etch-A-Snap is entirely portable and powered by 4xAA batteries & 3x18650 LiPo cells.

The developing time for a photo is approximately 15 minutes to 1 hour depending on complexity¹. The video below shows the Etch-A-Snap in action taking a photo.

Keep scrolling for some more examples.

Camera Examples

These shots were taken live using the Etch-A-Snap — a single shot was taken and immediately drawn to the screen. The drawing process was captured using a timelapse camera.

Selfie taken indoors against a plain background.

Outdoor street view, showing the Etch-A-Snap struggling a bit on building details.

Doraemon and a Deer shows a real-time recording of a snap. The image taken with the camera can be seen here for reference. In realtime you can see the initial print speed is slow as the graph is still being calculated, but then quickly increases. Print time is 6 minutes.

In early tests the Etch-A-Snap ran at 2 pixels per second, but now achieves a lightning fast 20 pixels per second.

Image examples

The Etch-A-Snap can also draw a picture from any image type supported by Pillow using the draw.py utility. Using this script the Etch-A-Snap crops, resizes and processes the images the exact same way as from the camera, but you can be a bit more selective with the image and increase the chances of getting something half decent out.

Andre Hazes generated from a stock photo with plain white background. This is probably the best photographic result produced, producing a pretty recognisable result.

Python logo generated from a colour PNG. The logo is on a plain white background, leaving it completely disconnected from the frame network. Linkers are added automatically.

Etch-A-Sketch logo generated from a monochrome PNG at 120x122.

The Queen. There is no route-optimisation (travelling salesman) at work when drawing, aside from adding weight to previously draw areas to encourage avoiding them in future. This picture of the Queen shows some serious back-tracking over the hair/top right corner. This picture was generated at 120x122.

How does it work?

If you're interested in how the Etch-A-Snap works, or want to build one yourself, take a look at the separate parts of the write-up — Build, Processing, Drawing and Plotter.

The following files and resources are also available —

The full code is available on Github along with a Jupyter notebook which details (and allows you to) experiment with the image processing and graph generation.
You can download the STL files for 3D printing, or edit the model on TinkerCad directly.
The circuit Fritzing file is also available.

It's quicker than film! ↩

Gyroscopic 3D wireframe cube — Using a 3-axis gyro for live 3D perspective

2019-01-11T08:00:00+00:00

This little project combines the previous accelerometer-gyroscope code with the 3D rotating OLED cube to produce a 3D cube which responds to gyro input, making it possible to "peek around" the cube with simulated perspective, or make it spin with a flick of the wrist.

Take a look at those earlier articles if you're interested in the background basics.

Requirements
Wemos D1 v2.2+ or good imitations.	amazon
3-axis Gyroscope Based on MPU6050 chip	amazon
0.96in OLED Screen 128x64 pixels, I2c interface.	amazon
Breadboard Any size will do.	amazon
Wires Loose ends, or jumper leads.

Libraries

We need two Python drivers for this project — one for the 128x64 OLED display, and one for the gyroscope.

The display in this example uses the ssd1306 chip, so we can use the module available in the MicroPython repository.

The gyroscope is a MPU6050, a Python library for which is available from @adamjezek98 here on Github.

Download both files and upload them to your controller using ampy or the web REPL.

Once the libraries are in place, connect to your controller and try and import both packages. If the imports work, you should be good to go.

python

import ssd1306
import mpu6050

Wiring

Both the ssd1306 display and the MPU6050 gyroscope-accelerometer communicte via I2C. Helpfully they're also on different channels, so we don't need to do any funny stuff to talk to them both at the same time.

The wiring is therefore quite simple, hooking them both up to +5V/GND and connecting their SCL and SDA pins to D1 and D2 respectively.

On the boards I have the the SDA, SCL, GND and 5V pins are in reverse order when the boards are placed pins-top. Double check what you're wiring where.

Code

The project is made up of 3 parts —

the gyroscope code to calibrate, retrieve and smooth the data
the 3D point code to handle the positions of cube in space
the simulation code to handle the inputs, and apply them to the 3D scene, outputting the result

First, the basic imports for I2C and the two libraries used for the display and gyro.

python

from machine import I2C, Pin
import ssd1306
import mpu6050
import math

i2c = I2C(scl=Pin(5), sda=Pin(4))
display = ssd1306.SSD1306_I2C(128, 64, i2c)
accel = mpu6050.accel(i2c)

Gyroscope

The gyroscope values can be a little noisy, and because of manufacturing variation (and gravity) need calibrating at rest before use.

Some standard smoothing and calibration code is shown below — to see a more thorough explanation of this see the introduction to 3-axis gyro-accelerometers in MicroPython.

First the smoothed sampling code which takes a number of samples and returns the mean average. It accepts a calibration input which provides a base value to remove from the resulting measurement.

python

def get_accel(n_samples=10, calibration=None):
    # Setup a dict of measure at 0
    result = {}
    for _ in range(n_samples):
        v = accel.get_values()

        for m in v.keys():
            # Add on value / n_samples (to generate an average)
            result[m] = result.get(m, 0) + v[m] / n_samples

    if calibration:
        # Remove calibration adjustment
        for m in calibration.keys():
            result[m] -= calibration[m]

    return result

The calibration code takes a number of samples, waiting for the variation to drop below threshold. It then returns this base offset for use in future calls to get_accel.

python

def calibrate(threshold=50):
    print('Calibrating...', end='')
    while True:
        v1 = get_accel(100)
        v2 = get_accel(100)
        if all(abs(v1[m] - v2[m]) < threshold for m in v1.keys()):
            print('Done.')
            return v1

Point3D objects

The simplest way to model objects in 3D space is to store and manipulate their vertices only — for a cube, that means the 8 corners.

To rotate the cube we manipulate these points in 3 dimensional space. To draw the cube, we project these points onto a 2-dimensional plane, to give a set of x,y coordinates, and connect the vertices with our edge lines.

The code here is based on this example for Pygame. The initial conversion of that code to MicroPython with an OLED screen and some background on the theory can be found here.

python

class Point3D:
    def __init__(self, x = 0, y = 0, z = 0):
        self.x, self.y, self.z = x, y, z

    def rotateX(self, deg):
        """ Rotates this point around the X axis the given number of degrees. """
        rad = deg * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        y = self.y * cosa - self.z * sina
        z = self.y * sina + self.z * cosa
        return Point3D(self.x, y, z)

    def rotateY(self, deg):
        """ Rotates this point around the Y axis the given number of degrees. """
        rad = deg * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        z = self.z * cosa - self.x * sina
        x = self.z * sina + self.x * cosa
        return Point3D(x, self.y, z)

    def rotateZ(self, deg):
        """ Rotates this point around the Z axis the given number of degrees. """
        rad = deg * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        x = self.x * cosa - self.y * sina
        y = self.x * sina + self.y * cosa
        return Point3D(x, y, self.z)

    def project(self, win_width, win_height, fov, viewer_distance):
        """ Transforms this 3D point to 2D using a perspective projection. """
        factor = fov / (viewer_distance + self.z)
        x = self.x * factor + win_width / 2
        y = -self.y * factor + win_height / 2
        return Point3D(x, y, self.z)

Gyro-locked Perspective Simulation

The first demo uses the accelerometer to produce a simulated perspective view of the cube. Tilting the board allows us to see "around" the edges of the cube, as if we were looking into the scene through a window.

To detect the angle of the device we're using the accelerometer. You might think to use the gyroscope first — I did — but remember the gyroscope detects angular velocity, not angle. Measurements are zero at rest, in any orientation. You can track the velocity changes and calculate the angle from this yourself, but gradually the error will build up and the cube will end up pointing the wrong way.

Using the accelerometer we have a defined rest point (flat on the surface) from which to calculate the current rotation. Placing the device flat will always return to the initial state.

python

class Simulation:
    def __init__(self, width=128, height=64, fov=64, distance=4):

        self.vertices = [
            Point3D(-1,1,-1),
            Point3D(1,1,-1),
            Point3D(1,-1,-1),
            Point3D(-1,-1,-1),
            Point3D(-1,1,1),
            Point3D(1,1,1),
            Point3D(1,-1,1),
            Point3D(-1,-1,1)
        ]

        # Define the edges, the numbers are indices to the vertices above.
        self.edges  = [
            # Back
            (0, 1), (1, 2), (2, 3), (3, 0),
            # Front
            (5, 4), (4, 7), (7, 6), (6, 5),
            # Front-to-back
            (0, 4), (1, 5), (2, 6), (3, 7),
        ]

        # Dimensions
        self.projection = [width, height, fov, distance]

    def run(self):
        # Starting angle (unrotated in any dimension)
        angleX, angleY, angleZ = 0, 0, 0

        calibration = calibrate()

        while 1:

            data = get_accel(10, calibration)

            angleX = data['AcX'] / 256
            angleY = data['AcY'] / 256

            t = []
            for v in self.vertices:
                # Rotate the point around X axis, then around Y axis, and finally around Z axis.
                r = v.rotateX(angleX).rotateY(angleY).rotateZ(angleZ)

                # Transform the point from 3D to 2D
                p = r.project(*self.projection)

                # Put the point in the list of transformed vertices
                t.append(p)

            display.fill(0)

            for e in self.edges:
                display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))

            display.show()

We use a simple helper function to convert lists of float into lists of int to make updating the OLED display simpler.

python

def to_int(*args):
    return [int(v) for v in args]

We can create a Simulation and run it with the following.

python

s = Simulation()
s.run()

Leave it on a flat surface as you start it up, so the calibration can complete quickly.

Once running it should look something like the following. If you pick up the device and tilt it you should notice the perspective of the cube change, as if you were 'looking around' the side of a real 3D cube.

{% youtube uesh3CcE0RA %}

Making it Spin

So far we've only used the accelerometer, and the cube has remained locked in a single position. This second demo uses the gyroscope to detect angular velocity allowing you to make the cube spin by flicking the device in one direction or another.

We do this by reading the velocity and adding it along a given axis. By reducing the velocity gradually over time, we can add a sense of friction to the rotation. The result is a cube that you can flick to rotate, that will gradually come to a rest.

The idea is to mimick the effect of a cube (e.g. a dice) floating inside a ball of liquid. Rotating it quickly adds momentum, which is gradually reduced by friction.

The simulation code is given below.

python

class Simulation:
    def __init__(
        self,
        width=128,
        height=64,
        fov=64,
        distance=4,
        inertia=10,
        acceleration=25,
        friction=1
        ):

        self.vertices = [
            Point3D(-1,1,-1),
            Point3D(1,1,-1),
            Point3D(1,-1,-1),
            Point3D(-1,-1,-1),
            Point3D(-1,1,1),
            Point3D(1,1,1),
            Point3D(1,-1,1),
            Point3D(-1,-1,1)
        ]

        # Define the edges, the numbers are indices to the vertices above.
        self.edges  = [
            # Back
            (0, 1), (1, 2), (2, 3), (3, 0),
            # Front
            (5, 4), (4, 7), (7, 6), (6, 5),
            # Front-to-back
            (0, 4), (1, 5), (2, 6), (3, 7),
        ]

        # Dimensions
        self.projection = [width, height, fov, distance]

        # Configuration
        self.friction = friction
        self.acceleration = acceleration
        self.inertia = inertia

    def run(self):
        velocityX, velocityY, velocityZ = 0, 0, 0
        calibration = calibrate()

        while 1:
            t = []

            # Get current rotational velocity from sensor.
            data = get_accel(10, calibration)
            gyroX = -data['GyY'] / 1024
            gyroY = data['GyX'] / 1024
            gyroZ = -data['GyZ'] / 1024

            # Apply velocity, with slide for friction.
            if abs(gyroX) > self.inertia:
                velocityX = slide_to_value(velocityX, gyroX, self.acceleration)

            if abs(gyroY) > self.inertia:
                velocityY = slide_to_value(velocityY, gyroY, self.acceleration)

            if abs(gyroZ) > self.inertia:
                velocityZ = slide_to_value(velocityZ, gyroZ, self.acceleration)

            rotated = []
            for v in self.vertices:
                r = v.rotateX(velocityX).rotateY(velocityY).rotateZ(velocityZ)
                p = r.project(*self.projection)
                t.append(p)
                rotated.append(r)

            self.vertices = rotated
            display.fill(0)

            for e in self.edges:
                display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))

            display.show()

            velocityX = slide_to_value(velocityX, 0, self.friction)
            velocityY = slide_to_value(velocityY, 0, self.friction)
            velocityZ = slide_to_value(velocityZ, 0, self.friction)

We need another helper function which handles the gradual "slide" of a given value towards it's target. This is used to both smooth acceleration and to gradually bleed off velocity via friction. The maximum value of change is specified by slide.

python

def slide_to_value(value, target, slide):
    """
    Move value towards target, with a maximum increase of slide.
    """
    difference = target-value
    if not difference:
        return value
    sign = abs(difference) / difference  # -1 if negative, 1 if positive
    return target if abs(difference) < slide else value + slide * sign

The simulation works as follows —

Read the rotational velocity from the gyroscope for each axis (X and Z axes are reversed because of the orientation of the sensor).
If the measured velocity in a given axis is higher than inertia we add move the current velocity towards the measured value, in steps of acceleration max.
The current velocities are used to update the vertices rotating them in 3D space, and storing the resulting updated positions. This is neccessary to ensure that the orientation of the axes for the view remain aligned with the frame of the gyroscope.
The display is drawn as before.
Finally we move all values towards zero by sliding towards zero, in steps of friction.

The end result is a 3D cube which responds to user input through the gyroscope, rotating along the appropriate axis. The inertia means small movements are ignored, so you can flick it in a given direction and then return it slowly to the original place and it will continue to spin.

{% youtube JJJxuqNs_f8 %}

You can experiment with the inertia, acceleration and friction values to see what effect they have. There is no real physics at work here, so you can create some quite weird behaviours.

3-axis Accelerometer-Gyro — Measuring acceleration and orientation with an MPU6050

2019-01-01T08:00:00+00:00

Measuring acceleration and rotation has a lot of useful applications, from drone or rocket stablisation to making physically interactive handheld games.

An accelerometer measures proper acceleration, meaning the rate of change of velocity relative to it's own rest frame. This is in contrast to coordinate acceleration, which is relative to a fixed coordinate system. The practical upshot of this is that at rest on Earth an accelerometer will measure acceleration due to the Earth's gravity, of g ≈ 9.81 m/s. An accelerometer in freefall will measure zero. This can be adjusted for with calibration.

A gyroscope (from Ancient Greek γῦρος "circle" and σκοπέω "to look") in contrast measures orientation and angular velocity, or rotation around an an axis. Angular velocity will always be zero at rest.

The availability of cheap single-chip accelerometer-gyroscope packages makes them practical for any project.

MPU6050

The MPU6050 is a nifty little 3-axis accelerometer and gyro package, providing measurements for acceleration along and rotation around 3 axes. It also contains an inbuilt temperature sensor. There are 4 configurable ranges for the gyro and accelerometer, meaning it can be used for both micro and macro measurements. Communication is via a simple I2C interface.

Gyro Full Scale Range (°/sec)	Gyro Sensitivity (LSB/°/sec)	Gyro Rate Noise (dps/√Hz)	Accel Full Scale Range (g)	Accel Sensitivity (LSB/g)
±250	131	0.005	±2	16384
±500	65.5	0.005	±4	8192
±1000	32.8	0.005	±8	4096
±2000	16.4	0.005	±16	2048

See the full MPU-6050 Product Specificiation.

Requirements
Wemos D1 v2.2+ or good imitations.	amazon
3-axis Gyroscope Based on MPU6050 chip	amazon
Breadboard Any size will do.	amazon
Wires Loose ends, or jumper leads.

Setting up

The MPU-6050 provides an I2C interface for communication. There are Python libraries available which simplify the communication further and return the measurements in a simple format. The examples here are using this MPU6050 library.

You can download the mpu6050.py file directly. Click Raw format and save the file with a .py extension. Upload the file to your device using ampy tool (or the WebREPL):

python

ampy --port /dev/tty.wchusbserial141120 put mpu6050.py

With the mpu6050.py file on your Wemos D1, you can import it as any other Python module. Connect to your device, and then in the REPL enter:

python

from machine import I2C, Pin
import mpu6050

If the import mpu6050 succeeds, the package is correctly uploaded and you're good to go.

Wire up the MPU6050, connecting pins D1 to SCL and D2 to SDA. Provide power from G and 5V. The light on the MPU6050 should light up once it's active.

Reading values

With the mpu6050 Python library on your device, and the MPU6050 module wired up, you can connect to the shell and start talking to it.

python

from machine import I2C, Pin
import mpu6050

i2c = I2C(scl=Pin(5), sda=Pin(4))
accel = mpu6050.accel(i2c)

With the accel object, we can read values from the sensor with .get_values(). This will return a dictionary of measurements from the sensor.

python

>>> accel.get_values()
{'GyZ': -46, 'GyY': -135, 'GyX': -1942, 'Tmp': 26.7888, 'AcZ': 24144, 'AcY': 68, 'AcX': -1004}

There are 3 sets of measurements returned from the sensor — acceleration, rotation (gyration) and temperature. The acceleration and rotation measurements provide 3 values each, one for each of the axes (X, Y, Z).

Measurement	Description
AcX	Acceleration along X axis
AcY	Acceleration along Y axis
AcZ	Acceleration along Z axis
GyX	Rotation around X axis
GyY	Rotation around Y axis
GyZ	Rotation around Z axis
Tmp	Temperature °C

The direction of the X and Y axes relative to the sensor are shown on the module itself. But you can always just adjust your code by trial and error.

Smoothing

If you repeatedly read measurements from the sensor in this way you'll notice that they're bouncing all over the place. This is normal for analog sensors. Before we can use the measurements from the sensor, we need to smooth out these random fluctuations to leave us with real representative data.

A simple way to do this is to read multiple values and take the mean (or median) of all the values. The sensor returns multiple values, so we need to average all of these individually.

python

def get_smoothed_values(n_samples=10):
    """
    Get smoothed values from the sensor by sampling
    the sensor `n_samples` times and returning the mean.
    """
    result = {}
    for _ in range(n_samples):
        data = accel.get_values()

        for k in data.keys():
            # Add on value / n_samples (to generate an average)
            # with default of 0 for first loop.
            result[k] = result.get(k, 0) + (data[k] / n_samples)

    return result

Running the above function will sample the sensor ten times, and return the averaged values.

python

>>> accel.get_values()
{'GyZ': -46, 'GyY': -135, 'GyX': -1942, 'Tmp': 26.7888, 'AcZ': 24144, 'AcY': 68, 'AcX': -1004}

If you repeatedly run this you should find the samples have stabilised quite a bit. As the values are in the range ±32768 the above measurements are actually pretty close to zero, though Z acceleration is notably higher. AcZ is the acceleration measurement in the Z (straight-up) axis and this value is the acceleration due to gravity of g ≈ 9.81 m/s.

The measured value 24144/16384 (at lowest measurement sensitivity) gives 1.47g so it's still off a bit.

The other offsets at rest are just inherent errors in the chip (individual, not the model), they're not interesting. To get our measurements centred around zero we can must identify this bias and adjust for it through calibration.

Calibration

If we take a number of repeated sensor measurements over time we can determine the standard, or average, deviation from zero over time. This offset can then be subtracted from future measurements to correct them. The device must be at rest and not changing for this to work reliably.

python

def calibrate(threshold=50, n_samples=100):
    """
    Get calibration date for the sensor, by repeatedly measuring
    while the sensor is stable. The resulting calibration
    dictionary contains offsets for this sensor in its
    current position.
    """
    while True:
        v1 = get_accel(n_samples)
        v2 = get_accel(n_samples)
        # Check all consecutive measurements are within
        # the threshold. We use abs() so all calculated
        # differences are positive.
        if all(abs(v1[k] - v2[k]) < threshold for k in v1.keys()):
            return v1  # Calibrated.

The all(abs(v1[k] - v2[k]) < threshold for key in v1.keys()) line is a bit of a beast. It iterates all the keys in our v1 dictionary, testing abs(v1[k] - v2[k]) for each. Here abs() gives us the absolute or positive difference, so we don't need to compare against negative threshold. Finally, all() tests that this is true for every key we've iterated.

Run this calibrate() function and wiggle the sensor around. You will see the device remain in the calibrating state, with the light flashing, while you wiggle it.

This is because while the device is moving, the difference between consecutive measurements will be greater than the defined threshold.

In the above calibration method we're testing all measurements from the sensor. You could of course only test some of them — e.g. only gyro or acceleration — depending on what you're using.

If you place your sensor onto the table, the calibration test will pass and the function will return values in the same format as for .get_values().

python

>>> calibrate()
{'GyZ': -46, 'GyY': -115, 'GyX': -1937, 'Tmp': 26.8359, 'AcZ': 23960, 'AcY': 44, 'AcX': -872}

The output dictionary of base measurements can be used to adjust subsequent measurements to remove this offset and recalibrate to zero at rest.

Below is an updated get_smoothed_values function which removes the calibrated offset before returning the smoothed data.

python

def get_smoothed_values(n_samples=10, calibration=None):
    """
    Get smoothed values from the sensor by sampling
    the sensor `n_samples` times and returning the mean.

    If passed a `calibration` dictionary, subtract these
    values from the final sensor value before returning.
    """
    result = {}
    for _ in range(n_samples):
        data = accel.get_values()

        for k in data.keys():
            # Add on value / n_samples to produce an average
            # over n_samples, with default of 0 for first loop.
            result[k] = result.get(k, 0) + (data[k] / n_samples)

    if calibration:
        # Remove calibration adjustment.
        for k in calibration.keys():
            result[k] -= calibration[k]

    return result

The following short snippet will allow you to see a table of the gyro and acceleration measurements in (very smoothed) real-time. The numbers are padded to stop them bouncing around as they change, and it uses control-characters to clear the terminal.

python

calibration = calibrate()
while True:
    data = get_smoothed_values(n_samples=100, calibration=calibration)
    print(
        '\t'.join('{0}:{1:>10.1f}'.format(k, data[k])
        for k in sorted(data.keys())),
    end='\r')

Running this you should see something like the following at rest:

python

AcX:     -17.7  AcY:      -3.2  AcZ:      -4.2  GyX:      -1.3  GyY:       1.9  GyZ:       1.8  Tmp:       0.0

If you pick up the sensor, you should see the Z acceleration increase, or decrease as you drop it. The X and Y acceleration should increase/decrease if you tilt the device in any direction. The acceleration measured here is acceleration due to gravity — if you tilt the device so the X axis is pointing straight down, all of g (≈ 9.81 m/s) will be acting through X, and none through Z.

python

AcX:   17679.9  AcY:     233.8  AcZ:  -16332.6  GyX:       3.9  GyY:      32.5  GyZ:       1.0  Tmp:      -0.2

Gyroscopic measurements show rotation around the relevant axis, so will always be zero at rest, but increase with rotational speed in each axis. For example if you rotate the device away from you, you should see a spike in the Y gyroscopic value, which returns to zero as the unit comes to a rest.

python

AcX:   -6540.4  AcY:      22.4  AcZ:   -1930.1  GyX:    -116.7  GyY:     748.9  GyZ:     211.3  Tmp:       0.0

If you pop your finger on the chip, you should also see the temperature raise very slightly.

python

AcX:    -547.8  AcY:      29.8  AcZ:     -36.0  GyX:      -6.9  GyY:       8.9  GyZ:      -3.8  Tmp:       0.3

This covers the basic work of interfacing with an MPU6050 from MicroPython. I'll be adding some projects using this chip shortly.

Dictionary Views & Set Operations — Working with dictionary view objects

2018-09-30T06:00:00+00:00

The keys, values and items from a dictionary can be accessed using the .keys(), .values() and .items() methods. These methods return view objects which provide a view on the source dictionary.

The view objects dict_keys and dict_items support set-like operations (the latter only when all values are hashable) which can be used to combine and filter dictionary elements.

Keys

Dictionary keys are always hashable, so set operations are always available on the dict_keys view object.

All keys (`set` union)

To get all keys from multiple dictionaries, you can use the set union.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.keys() | d2.keys()
{'key5', 'key3', 'key2', 'key1'}  # this is a set, not a dict

You can use the same approach to combine dict_items and merge dictionaries.

Keys in common (`set` intersection)

The keys common to two dictionaries can be determined using set intersection (&).

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.keys() & d2.keys()
{'key3'}    # this is a set, not a dictionary

You could use the resulting set to filter your dictionary using a dictionary comprehension.

python

>>> {k:d1[k] for k in keys}
{'key2':'value2', 'key1':'value1'}

Unique keys (`set` difference)

To retrieve keys unique to a given dictionary, you can use set difference (-). Keys from the right hand dict_keys are removed from the left, resulting in a set of the remaining keys.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.keys() - d2.keys()
{'key1', 'key2'}

Unique keys from both (`set` symmetric difference)

If you want items unique to both dictionaries, the set symmetric difference (^) returns this. The result is items unique to both the left and right hand of the comparison.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.keys() ^ d2.keys()
{'key5', 'key2', 'key1'}

Items

If both the keys and values of a dictionary are hashable, the dict_items view will support set-like operations.

If the values are not hashable all of these2 operations will all raise a TypeError.

Merge (`set` union)

You can use set union operations to merge two dictionaries.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}
>>> d3 = {'key4':'value4', 'key6':'value6'}

>>> d = dict(d1.items() | d2.items() | d3.items())
>>> d
{'key1':'value1', 'key2':'value2', 'key3':'value3-new', 'key5':'value5', 'key4':'value4', 'key6':'value6'}

Since it is quite common for dictionary values to not be hashable, you will probably want to use one of the other approaches for merging dictionaries instead.

Common entries (`set` intersection)

The items common to two dictionaries can be determined using set intersection (&). Both the key and value must match — items are compared as (key, value) tuples.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key1':'value1', 'key5':'value5'}

>>> d1.items() & d2.items()
{('key1', 'value1')}    # this is a set, not a dict

Unique entries (`set` difference)

To retrieve items unique to a given dictionary, you can use set difference (-). Items from the right hand dict_keys are removed from the left, resulting in a set of the remaining item (key, value) tuples.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.items() - d2.items()
{('key3', 3), ('key2', 'value2'), ('key1', 'value1')}

Unique entries from both (`set` symmetric difference)

If you want items unique to both dictionaries, the set symmetric difference (^) returns this. The result is item (key, value) tuples unique to both the left and right hand of the comparison.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.items() ^ d2.items()
{('key2', 'value2'), ('key5', 'value5'), ('key1', 'value1'), ('key3', 3), ('key3', 'value3-new')}

Creating a 3D wireframe cube with MicroPython on an OLED display — Basic 3D model rotation and projection

2018-09-23T07:00:00+00:00

An ESP2866 is never going to compete with an actual graphics card. But it has more than enough oomph to explore the fundamentals of 3D graphics. In this short tutorial we'll go through the basics of creating a 3D scene and displaying it on an OLED screen using MicroPython.

This kind of mono wireframe 3D reminds me of early ZX Spectrum 3D games which mostly involved shooting one wobbly line at another, and looking at the resulting wobbly lines. It was awesome.

The 3D code here is based on this example for Pygame with some simplifications and the display code modified for working with framebuf.

Requirements

Wemos D1 v2.2+ or good imitations.
0.96in OLED Screen 128x64 pixels, I2c interface.
Breadboard Any size will do.
Wires (Loose ends, or jumper leads.)

Setting up

The display used here is a 128x64 OLED which communicates over I2C. We're using the ssd1306 module for OLED displays available in the MicroPython repository to handle this communication for us, and provide a framebuf drawing interface.

Upload the ssd1306.py file to your device's filesystem using the ampy tool (or the WebREPL).

bash

ampy --port /dev/tty.wchusbserial141120 put ssd1306.py

With the ssd1306.py file on your Wemos D1, you should be able to import it as any other Python module. Connect to your device, and then in the REPL enter:

python

from machine import I2C, Pin
import ssd1306

If the import ssd1306 succeeds, the package is correctly uploaded and you're good to go.

Wire up the OLED display, connecting pins D1 to SCL and D2 to SDA.Provide power from G and 5V.

To work with the display, we need to create an I2C object, connecting via pins D1 and D2 — hardware pin 4 & 5 respectively. Passing the resulting i2c object into our SSD1306_I2C class, along with screen dimensions, gets us our interface to draw with.

python

from machine import I2C, Pin
import ssd1306
import math


i2c = I2C(scl=Pin(5), sda=Pin(4))
display = ssd1306.SSD1306_I2C(128, 64, i2c)

Modelling 3D objects

The simplest way to model objects in 3D space is to store and manipulate their vertices only — for a cube, that means the 8 corners.

To rotate the cube we manipulate these points in 3 dimensional space. To draw the cube, we project these points onto a 2-dimensional plane, to give a set of x,y coordinates, and connect the vertices with our edge lines.

Rotation along each axis and the projection onto a 2D plane is described below.

The full code is available for download here if you want to skip ahead and start experimenting.

3D Rotation

Rotating an object in 3 dimensions is no different than rotating a object on a 2D surface, it's just a matter of perspective.

Take a square drawn on a flat piece of paper, and rotate it 90°. If you look before and after rotation the X and Y coordinates of any given corner change, but the square is still flat on the paper. This is analogous to rotating any 3D object along it's Z axis — the axis that is coming out of the middle of the object and straight up.

The same applies to rotation along any axis — the coordinates in the axis of rotation remain unchanged, while coordinates along other axes are modified.

python

# Rotation along X
y' = y*cos(a) - z*sin(a)
z' = y*sin(a) + z*cos(a)
x' = x


# Rotation along Y
z' = z*cos(a) - x*sin(a)
x' = z*sin(a) + x*cos(a)
y' = y

# Rotation along Z
x' = x*cos(a) - y*sin(a)
y' = x*sin(a) + y*cos(a)
z' = z

The equivalent Python code for the rotation along the X axis is shown below. It maps directly to the math already described. Note that when rotating in the X dimension, the x coordinates are returned unchanged and we also need to convert from degrees to radians (we could of course write this function to accept radians instead).

python

def rotateX(self, x, y, z, deg):
    """ Rotates this point around the X axis the given number of degrees. Return the x, y, z coordinates of the result"""
    rad = deg * math.pi / 180
    cosa = math.cos(rad)
    sina = math.sin(rad)
    y = y * cosa - z * sina
    z = y * sina + z * cosa
    return x, y, z

Projection

Since we're displaying our 3D objects on a 2D surface we need to be able to convert, or project, the 3D coordinates onto 2D. The approach we are using here is perspective projection.

If you imagine an object moving away from you, it gradually shrinks in size until it disappears into the distance. If it is directly in front of you, the edges of the object will gradually move towards the middle as it recedes. Similarly, a large square transparent object will have the rear edges appear 'within' the bounds of the front edges. This is perspective.

To recreate this in our 2D projection, we need to move points towards the middle of our screen the further away from our 'viewer' they are. Our x & y coordinates are zero'd around the center of the screen (an x < 0 means to the left of the center point), so dividing x & y coordinates by some amount of Z will move them towards the middle, appearing 'further away'.

The specific formula we're using is shown below. We take into account the field of view — how much of an area the viewer can see — the viewer distance and the screen height and width to project onto our framebuf.

python

x' = x * fov / (z + viewer_distance) + screen_width / 2
y' = -y * fov / (z + viewer_distance) + screen_height / 2

Point3D code

The complete code for a single Point3D is shown below, containing the methods for rotation in all 3 axes, and for projection onto a 2D plane. Each of these methods return a new Point3D object, allow us to chain multiple transformations and avoid altering the original points we define.

python

class Point3D:
    def __init__(self, x = 0, y = 0, z = 0):
        self.x, self.y, self.z = x, y, z

    def rotateX(self, angle):
        """ Rotates this point around the X axis the given number of degrees. """
        rad = angle * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        y = self.y * cosa - self.z * sina
        z = self.y * sina + self.z * cosa
        return Point3D(self.x, y, z)

    def rotateY(self, angle):
        """ Rotates this point around the Y axis the given number of degrees. """
        rad = angle * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        z = self.z * cosa - self.x * sina
        x = self.z * sina + self.x * cosa
        return Point3D(x, self.y, z)

    def rotateZ(self, angle):
        """ Rotates this point around the Z axis the given number of degrees. """
        rad = angle * math.pi / 180
        cosa = math.cos(rad)
        sina = math.sin(rad)
        x = self.x * cosa - self.y * sina
        y = self.x * sina + self.y * cosa
        return Point3D(x, y, self.z)

    def project(self, win_width, win_height, fov, viewer_distance):
        """ Transforms this 3D point to 2D using a perspective projection. """
        factor = fov / (viewer_distance + self.z)
        x = self.x * factor + win_width / 2
        y = -self.y * factor + win_height / 2
        return Point3D(x, y, self.z)

3D Simulation

We can now create a scene by arranging Point3D objects in 3-dimensional space. To create a cube, rather than 8 discrete points, we will connect our vertices to their adjacent vertices after projecting them onto our 2D surface.

Vertices

The vertices for a cube are shown below. Our cube is centered around 0 in all 3 axes, and rotates around this centre.

python

self.vertices = [
    Point3D(-1,1,-1),
    Point3D(1,1,-1),
    Point3D(1,-1,-1),
    Point3D(-1,-1,-1),
    Point3D(-1,1,1),
    Point3D(1,1,1),
    Point3D(1,-1,1),
    Point3D(-1,-1,1)
]

Polygons or Lines

As we're drawing a wireframe cube, we actually have a couple of options — polygons or lines.

The cube has 6 faces, which means 6 polygons. To draw a single polygon requires 4 lines, making a total draw for the wireframe cube with polygons of 24 lines. We draw more lines than needed, because each polygon shares sides with 4 others.

In contrast drawing only the lines that are required, a wireframe of the cube can be drawn using only 12 lines — half as many.

For a filled cube, polygons would make sense, but here we're going to use the lines only, which we call edges. This is an array of indices into our vertices list.

python

self.edges  = [
    # Back
    (0, 1),
    (1, 2),
    (2, 3),
    (3, 0),
    # Front
    (5, 4),
    (4, 7),
    (7, 6),
    (6, 5),
    # Front-to-back
    (0, 5),
    (1, 4),
    (2, 7),
    (3, 6),
]

On each iteration we apply the rotational transformations to each point, then project it onto our 2D surface.

python

r = v.rotateX(angleX).rotateY(angleY).rotateZ(angleZ)

# Transform the point from 3D to 2D
p = r.project(*self.projection)

# Put the point in the list of transformed vertices
t.append(p)

Then we iterate our list of edges, and retrieve the relevant transformed vertices from our list t. A line is then drawn between the x, y coordinates of two points making up the edge.

python

for e in self.edges:
    display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))

The to_int is just a simple helper function to convert lists of float into lists of int to make updating the OLED display simpler (you can't draw half a pixel).

python

def to_int(*args):
    return [int(v) for v in args]

The complete simulation code is given below.

python

class Simulation:
    def __init__(self, width=128, height=64, fov=64, distance=4, rotateX=5, rotateY=5, rotateZ=5):

        self.vertices = [
            Point3D(-1, 1,-1),
            Point3D( 1, 1,-1),
            Point3D( 1,-1,-1),
            Point3D(-1,-1,-1),
            Point3D(-1, 1, 1),
            Point3D( 1, 1, 1),
            Point3D( 1,-1, 1),
            Point3D(-1,-1, 1)
        ]

        # Define the edges, the numbers are indices to the vertices above.
        self.edges  = [
            # Back
            (0, 1), (1, 2), (2, 3), (3, 0),
            # Front
            (5, 4), (4, 7), (7, 6), (6, 5),
            # Front-to-back
            (0, 4), (1, 5), (2, 6), (3, 7),
        ]

        # Dimensions
        self.projection = [width, height, fov, distance]

        # Rotational speeds
        self.rotateX = rotateX
        self.rotateY = rotateY
        self.rotateZ = rotateZ

    def run(self):
        # Starting angle (unrotated in any dimension).
        angleX, angleY, angleZ = 0, 0, 0

        while 1:
            t = []
            for v in self.vertices:
                # Rotate the point around X axis, then around Y axis, and finally around Z axis.
                r = v.rotateX(angleX).rotateY(angleY).rotateZ(angleZ)

                # Transform the point from 3D to 2D
                p = r.project(*self.projection)

                # Put the point in the list of transformed vertices.
                t.append(p)

            display.fill(0)

            for e in self.edges:
                display.line(*to_int(t[e[0]].x, t[e[0]].y, t[e[1]].x, t[e[1]].y, 1))

            display.show()

            # Continue the rotation.
            angleX += self.rotateX
            angleY += self.rotateY
            angleZ += self.rotateZ

Running a simulation

To display our cube we need to create a Simulation object, and then call .run() to start it running.

python

s = Simulation()
s.run()

You can pass in different values for rotateX, rotateY, rotateZ to alter the speed of rotation. Set a negative value to rotate in reverse.

python

s = Simulation()
s.run()

The fov and distance parameters are set at sensible values for the 128x64 OLED by default (based on testing). So you don't need to change these, but you can.

python

s = Simulation(fov=32, distance=8)
s.run()

The width and height are defined by the display, so you won't want to change these unless you're using a different display output.

Displaying images on OLED screens — Using 1-bpp images in MicroPython

2018-08-27T16:00:00+00:00

We've previously covered the basics of driving OLED I2C displays from MicroPython, including simple graphics commands and text. Here we look at displaying monochrome 1 bit-per-pixel images and animations using MicroPython on a Wemos D1.

Processing the images and correct choice of image-formats is important to get the most detail, and to not run out of memory.

Requirements
Wemos D1 v2.2+ or good imitations.	amazon
0.96in OLED Screen 128x64 pixels, I2c interface.	amazon
Breadboard Any size will do.	amazon
Wires Loose ends, or jumper leads.

Setting up

The display communicates over I2C, but we need a driver to interface with it. You can import ssd1306 as any other Python module. Connect to your device, and then in the REPL enter:

python

from machine import I2C, Pin
import ssd1306
import framebuf

If the import ssd1306 succeeds, the package is correctly uploaded and you're good to go.

Wire up the OLED display, connecting pins D1 to SCL and D2 to SDA. Provide power from G and 5V. The display below is a 2-colour version, where the top 1/4 of the pixels are yellow, while the rest is blue. They're intended for mobile screens, but it looks kind of neat with Scatman.

python

i2c = I2C(-1, Pin(5), Pin(4))
display = ssd1306.SSD1306_I2C(128, 64, i2c)

If your display is a different size just fiddle the numbers above. You'll need to change some parameters on loops later too.

To test the display is working, let's set all the pixels to on and show it.

python

display.fill(1)
display.show()

The screen should light up completely. If it doesn't, something is wrong.

Image Processing

To display an image on a 1-bit per pixel monochrome display we need to get our image into the same format. The best way to do this is using image manipulation software, such as Photoshop or GIMP. These allow you to down-sample the image to monochrome while maintaining detail by adding dither or other adjustments.

The first step is to crop the image down to the correct dimensions — the display used here is 128x64 pixels. To preserve as much of the image as possible you might find it useful to resize the larger axis to the max (e.g. if the image is wider than high, resize the width to 128 pixels). Then crop the remaining axis.

You can convert images to 1-bit-per-pixel in GIMP through the Image -> Mode -> Indexed... dialog.

If you're image is already in an indexed format this won't be available. So convert back to RGB/Grayscale first, then re-select Image -> Mode -> Indexed.

Select "Use black and white (1-bit) palette" to enable 1bpp mode. The colour dithering settings are best chosen by trial and error depending on the image being converted although turning off dithering entirely is often best for images of solid colour blocks (e.g. logos).

Once the imagine is converted to black & white you can save to file. There are two good options for saving 1bpp images — PBM and PGM. PBM is a 1 bit-per-pixel format, while PGM is grayscale 1 byte per pixel.

Type	Magic number (ASCII)	Magic number (Binary)	Extension	Colors
Portable BitMap	P1	P4	.pbm	0–1 (white & black)
Portable GrayMap	P2	P5	.pgm	0–255 (gray scale)
Portable PixMap	P3	P6	.ppm	0–255 (RGB)

While PBM is clearly better suited, we can pre-process PGM down to an equivalent bit stream. Both approaches are included here, in case your software can only produce one or the other.

Save as either PBM (recommended) or PGM, and select Raw mode, not ASCII.

Example images

Some example images (128x64 pixels) are shown below, in PNG format. Each of the images is available in this zip which contains PBM, PGM and PNG formats.

Portable Bitmap Format

Portable Bitmap Format (PBM) format consists of a regular header, separated by newlines, then the image data. The header starts with a magic number indicating the image format and whether the format is ASCII for binary. In all examples here we're using binary since it's more compact. The second line is a comment, which is usually the program used to create it. Third are the image dimensions. Then, following a final newline, you get the image binary blob.

python

P4
# CREATOR: GIMP PNM Filter Version 1.1
128 64
<data>

The data is stored as a 1-bit-per-pixel stream, with pixel on as 1 pixel off as 0. On a normal display screen an on pixel appears as black — this is different on the OLED, which we need to account for later.

To upload your PBM file to the controller —

bash

ampy --port /dev/tty.wchusbserial141120 put alan.pbm

Loading images

The PBM data stream is already in the correct format for use. We can wrap the data in bytearray, use this to create a FrameBuffer and blit it immediately. However, we need to skip the header region (3x readline) before reading the subsequent data block.

python

with open('scatman.pbm', 'rb') as f:
    f.readline() # Magic number
    f.readline() # Creator comment
    f.readline() # Dimensions
    data = bytearray(f.read())
fbuf = framebuf.FrameBuffer(data, 128, 64, framebuf.MONO_HLSB)

We can't use readlines() since the binary image data may contain ASCII code 13 (newline).

The framebuf.MONO_HLSB format is desribed in the MicroPython docs as —

Monochrome (1-bit) color format This defines a mapping where the bits in a byte are horizontally mapped. Each byte occupies 8 horizontal pixels with bit 0 being the leftmost. Subsequent bytes appear at successive horizontal locations until the rightmost edge is reached. Further bytes are rendered on the next row, one pixel lower.

This matches exactly with the format of our PBM data.

This framebuffer format framebuf.MONO_HLSB used is different to that used by the ssd1306 screen (framebuf.MONO_VLSB). This is handled transparently by the framebuffer when blitting.

Displaying an image

We have the image data in fbuf, which can be blitted directly to our display framebuffer, using .blit. This accepts coordinates at which to blit. Because the OLED screen displays inverse (on = light, off = black) we need to switch .invert(1) on the display.

python

display.invert(1)
display.blit(fbuf, 0, 0)
display.show()

Portable Graymap Format

Portable Graymap Format (PGM) format shares a similar header to PBM, again newline separated. However, there is an additional 4th header line which contains the max value — indicating the number of values between black and white. Black is again zero, max (255 here) is white.

python

P5
# CREATOR: GIMP PNM Filter Version 1.1
128 64
255
<data>

The format uses 1 byte per pixel. This is 8x too many for our purposes, but we can process it down to 1bpp. Since we're saving a mono image each pixel will contain either 0 (fully off) or 255 (fully on).

To upload your PGM file to the controller —

bash

ampy --port /dev/tty.wchusbserial141120 put alan.pgm

Loading images

Since each pixel is a single byte it is easy to iterate, though slow as hell. We opt here to turn on bright pixels, which gives us the correct output without switching the display invert on.

python

with open('alan.pgm', 'rb') as f:
    f.readline() # Magic number
    f.readline() # Creator comment
    f.readline() # Dimensions
    data = bytearray(f.read())

for x in range(128):
    for y in range(32):
        c = data[x + y*128]
        display.pixel(x, y, 1 if c == 255 else 0)

Packing bits

Using 1 byte per pixel wastes 7 bits which is not great, and iterating to draw the pixels is slow. If we pack the bits we can blit as we did with PBM. To do this we simply iterate over the PGM image data in blocks of 8 (8 bits=1 byte).

Each iteration we create our zero'd-byte (an int of 0). As we iterate over the 8 bits, we add 2**(7-n) if that bit should be set to on. The first byte we hit sets the topmost bit, which has a value of 2**(7-0) = 2**7 = 128, the second 2**(7-1) = 2**6 = 64. The table below shows the values for each bit in a byte.

python

|7| 6|5|4|3|2|1|0
|:--|:--|:--|:--|:--|:--|:--|:--|
|2^7|   2^6|2^5|2^4|2^3|2^2|2^1|2^0|
|128|   64|32|16|8|4|2|1|

The result is a single byte with a single bit set in turn for each byte we iterated over.

python

p = []
for i in range(0, len(d), 8):
    byte = 0
    for n, bit in enumerate(d[i:i+8]):
        byte += 2**(7-n) if bit == 255 else 0

    p.append(byte)

We choose to interpret the 255 values as on (the opposite as in PBM where black = on, giving an inverted image). You could of course reverse it.

The variable p now contains a list of int values in the range 0-255 (bytes). We can cast this to a bytearray and then use this create our FrameBuffer object.

python

# Create a framebuffer object
fbuf = framebuf.FrameBuffer(bytearray(p), 128, 64, framebuf.MONO_HLSB)

The framebuf.MONO_HLSB format is desribed in the MicroPython docs as —

Monochrome (1-bit) color format This defines a mapping where the bits in a byte are horizontally mapped. Each byte occupies 8 horizontal pixels with bit 0 being the leftmost. Subsequent bytes appear at successive horizontal locations until the rightmost edge is reached. Further bytes are rendered on the next row, one pixel lower.

This matches exactly with the format of our PGM (and bit-packed) data.

This framebuffer format framebuf.MONO_HLSB used is different to that used by the ssd1306 screen (framebuf.MONO_VLSB). This is handled transparently by the framebuffer when blitting.

Packing script

A command-line packing script is given below (and you can download it here), which can be used to pack a PGM into a 1bpp bitstream. The script accepts a single filename of a PGM file to process, and outputs the resulting packed bit data as <filename>.bin.

python

import os
import sys

fn = sys.argv[1]

with open(fn, 'rb') as f:
    f.readline() # Magic number
    f.readline() # Creator comment
    f.readline() # Dimensions
    f.readline() # Max value, 255
    data = bytearray(f.read())

p = []
for i in range(0, len(data), 8):
    byte = 0
    for n, bit in enumerate(data[i:i+8]):
        byte += 2**(7-n) if bit == 255 else 0

    p.append(byte)

b = bytearray(p)

basename, _ = os.path.splitext(fn)
with open('%s.bin' % basename, 'wb') as f:
    f.write(b)

The resulting file is 1KB in size, and identical to a .pbm format file, minus the header and with colours inverted (this makes display simpler).

bash

python pack.py scatman.1.pgm

ls -l

-rw-r--r--  1 martin  staff  1024 26 Aug 18:11 scatman.bin
-rw-r--r--  1 martin  staff  8245 26 Aug 18:02 scatman.pgm

To upload your BIN file to the controller —

bash

ampy --port /dev/tty.wchusbserial141120 put scatman.bin

Loading images

Since we've stripped off the PGM header, the resulting file can be read directly into a bytearray.

python

with open('scatman.bin', 'rb') as f:
    data = bytearray(f.read())

fbuf = framebuf.FrameBuffer(data, 128, 64, framebuf.MONO_HLSB)

The colours were inverted in our bit packer so we can just blit the framebuffer directly without inverting the display.

python

display.blit(fbuf, 0, 0)
display.show()

Animation

Both the PBM and PGM images are 1KB in memory once loaded, leaving us plenty of space to load multiple images and animate them. The following loads a series of Scatman John PBM images and animates them in a loop.

python

from machine import I2C, Pin
import ssd1306
import time
import framebuf

i2c = I2C(-1, Pin(5), Pin(4))
display = ssd1306.SSD1306_I2C(128, 64, i2c)

images = []
for n in range(1,7):
    with open('scatman.%s.pbm' % n, 'rb') as f:
        f.readline() # Magic number
        f.readline() # Creator comment
        f.readline() # Dimensions
        data = bytearray(f.read())
    fbuf = framebuf.FrameBuffer(data, 128, 64, framebuf.MONO_HLSB)
    images.append(fbuf)

display.invert(1)
while True:
    for i in images:
        display.blit(i, 0, 0)
        display.show()
        time.sleep(0.1)

The resulting animation —

The image distortion is due to frame rate mismatch with the camera and won't be visible in person.

Optimization

There is still plenty of room left for optimization. For static images there are often multiple consecutive blocks of bits of the same colour (think backround regions) or regular patterns (dithering). By setting aside a few bits as repeat markers we could compress these regions down to a single pattern, at the cost of random larger files for very random images and unpacking time.

We could get away with a lot less data for the animation (particularly the example above) by storing only frame deltas (changes), and using key frames. But we'd also need masking, and that takes memory... and yeah. Let's not, for now.

Dictionaries — A rather long guide to Python's key:value hash type

2018-08-26T12:00:00+00:00

Dictionaries are key-value stores, meaning they store, and allow retrieval of data (or values) through a unique key. This is analogous with a real dictionary where you look up definitions (data) using a given key — the word. Unlike a language dictionary however, keys in Python dictionaries are not alphabetically sorted.

From Python 3.6 onwards dictionaries are ordered in that elements are stored and retrieved in the order in which they are added. This usually only has consequences for iterating (see later).

Anything which can be stored in a Python variable can be stored in a dictionary value. That includes mutable types including list and even dict — meaning you can nest dictionaries inside on another. In contrast keys must be hashable and immutable — the object hash must not change once calculated. This means list or dict objects cannot be used for dictionary keys, however a tuple is fine.

A hash is a reproducible, compact, representation of an original value. Reproducible means that hashing the same input will always produce the same output. This is essential for dictionary keys where hashes are used to store and look up values: if the hash changed each time we hashed the key, we'd never find anything!

Creating

Dictionaries can be defined using both literal or constructor syntax. Literal syntax is a bit cleaner, but there are situations where dict() is useful.

python

d = {}        # An empty dictionary, using literal syntax
d = dict()    # An empty dictionary, using object syntax

You can add initial items to a dictionary by passing the key-value pairs at creation time. The following two syntaxes are equivalent, and will produce an identical dictionary.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}
>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> d = dict(key1='value1', key2='value2', key3=3)
>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

However, note that keys in the dict syntax are limited to valid keyword parameter names only — for example, you cannot use anything which would not be a valid variable name (including numbers, number-initial alphanumeric names or punctuation).

python

>>> dict(1='hello')
SyntaxError: invalid syntax

>>> dict(1a='hello')
SyntaxError: invalid syntax

As always in Python, keyword parameters are interpreted as string names, ignoring any variables defined with the same name.

python

>>> a = 12345
>>> {a:'test'}
{12345: 'test'}

>>> dict(a='test')
{'a': 'test'}

For this reason dict() is only really useful where you have very restricted key names. This is often the case, but you can avoid these annoyances completely by sticking with the literal {} syntax.

Adding

You can add items to a dictionary by assigning a value to a key, using the square bracket [] syntax.

python

>>> d = {}
>>> d['this'] = 'that'
>>> d
{'this':'that'}

Assigning to keys which already exist will replace the existing value for that key.

python

>>> d = {}
>>> d['this'] = 'that'
>>> d['this'] = 'the other'
>>> d
{'this':'the other'}

Retrieving

Values for a given key can be retrieved by key, using the square bracket [] syntax.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}
>>> d['key1']
'value1'

Retrieving an item does not remove it from the dictionary.

python

>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

The value returned is the same object stored in the dictionary, not a copy. This is important to bear in mind when using mutable objects such as lists as values.

python

>>> d = {'key1': [1,2,3,4]}
>>> l = d['key1']
>>> l
[1,2,3,4]

>>> l.pop()
4

>>> d
d = {'key1': [1,2,3]}

Notice that changes made to the returned list continue to be reflected in the dictionary. The retrieved list and the value in the dictionary are the same object.

Removing

To remove an item from a dictionary you can use del using square bracket syntax with the key to access the element.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> del d['key1]
>>> d
{'key2':'value2', 'key3': 3}

You can also remove items from a dictionary by using .pop(<key>). This removes the given key from the dictionary, and returns the value.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> d.pop('key1)
'value1'

>>> d
{'key2':'value2', 'key3': 3}

Counting

The number of elements in a dictionary can be found by using len().

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}
>>> len(d)
3

The length of a dictionaries .keys(), .values() and .items() are always equal.

View objects

There are separate view objects for each of keys, values and items — dict_keys, dict_values and dict_items respectively.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}
>>> d.keys()
dict_keys(['key1', 'key2', 'key3'])

>>> d.values()
dict_values(['value1', 'value2', 3])

dict_items provides a view over tuples of (key, value) pairs.

python

>>> d.items()
dict_items([('key1', 'value1'), ('key2', 'value2'), ('key3', 3)])

These view objects are all iterable. They are also dynamic — changes to the original dictionary continue to be reflected in the view after it is created.

python

>>> k = d.keys()
>>> k
dict_keys(['key1', 'key2', 'key3'])

>>> d['key4'] = 'value4'
>>> k
dict_keys(['key1', 'key2', 'key3', 'key4'])

This is different to Python 2.7, where .keys(), .values() and .items() returned a static list.

Membership

To determine if a given key is present in a dictionary, you can use the in keyword. This will return True if the give key is found, False if it is not.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> 'key2' in d
True

>>> 'key5' in d
False

You can also check whether a given value or key-value pair is in a dictionary by using the .values() and .items() views.

python

>>> 'value1' in d.values()
True

>>> 'value5' in d.values()
False

>>> ('key1', 'value1') in d.items()
True

>>> ('key3', 'value5') in d.items()
False

These lookups are less efficient that key-based lookups on dictionaries, and needing to lookup values or items is often an indication that a dict is not a good store for your data.

Lists from dictionaries

To get a list of a dictionary's keys, values or items of a dictionary to lists, we can take the dict_keys, dict_values or dict_items view objects and pass them to list().

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> list(d.keys())
['key1', 'key2', 'key3']

>>> list(d.values())
['value1', 'value2', 3]

>>> list(d.items())
[('key1', 'value1'), ('key2', 'value2'), ('key3', 3)]

Converting the view objects to lists breaks the link to the original dictionary, so further updates to the dictionary will not be reflected in the list.

Dictionaries from lists

Similarly lists can be used to generate dictionaries. The simplest approach is using a list of 2-tuple where the first element in the tuple is used for the key and the second for the value.

python

>>> l = [('key1', 'value1'), ('key2', 'value2'), ('key3', 3)]
>>> d = dict(l) # Pass the list as to the dict constructor

>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

You can pass in other iterators, not just lists. The only restriction is that the iterator needs to return 2 items per iteration.

If you have your key and value elements in seperate lists, you can use zip to combine them together into tuples before creating the dictionary.

python

>>> keys = ['key1', 'key2', 'key3']
>>> vals = ['value1', 'value2', 3]

>>> l = zip(keys, vals)
>>> l
<zip object>

>>> dict(l)
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

If key and value lists are not of the same length, the behaviour of zip is to silently drop any extra items from the longer list.

python

>>> keys = ['key1', 'key2', 'oops']
>>> vals = ['value1', 'value2']

>>> dict(zip(keys, vals))
{'key1': 'value1', 'key2': 'value2'}

Iterating

By default iterating over a dictionary iterates over the keys.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> for k in d:
...     print(k)
key1
key2
key3

This is functionally equivalent to iterating over the .keys() view.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> for k in d.keys():
...     print(k)
key1
key2
key3

The dictionary is unaffected by iterating over it, and you can use the key within your loop to access the value from the dictionary.

python

>>> d = {'key1': 'value1', 'key2': 'value2', 'key3': 3}

>>> for k in d:
...     print(k, d[k])  # Access value by key.
key1 value1
key2 value2
key3 3

If you want access to dictionary values within your loop, you can iterate over items to have them returned in the for loop. The keys vand values are returned as a 2-tuple.

python

>>> d = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> for kv in d.items():
...     print(kv)
('key1', 'value1')
('key2', 'value2')
('key3', 3)

You can unpack the key and value to seperate variables in the loop, making them available without indexing. This is the most common loop structure used with dictionaries.

python

>>> d = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> for k, v in d.items():
...     print(k, v)
key1 value1
key2 value2
key3 3

If you are only interested in the dictionary values you can also iterate over these directly.

python

>>> d = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> for v in d.values():
...     print(v)
value1
value2
3

If you want to count as you iterate you can use enumerate as with any iterator, but you must nest the unpacking.

python

>>> d = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> for n, (k, v) in enumerate(d.items()):
...     print(n, k, v)
0 key1 value1
1 key2 value2
2 key3 3

Dictionary comprehensions

Dictionary comprehensions are shorthand iterations which can be used to construct dictionaries, while filtering or altering keys or values.

Iterating over a list of (key, value) tuples and assigning to keys and values will create a new dictionary.

python

>>> l = [('key1','value1'), ('key2','value2'), ('key3',3)]

>>> {k:v for k,v in l}
{'key1': 'value1', 'key2': 'value2', 'key3': 3}

You can filter elements by using a trailing if clause. If this expression evaluates to False the element will be skipped (if it evaluates True it will be added).

python

>>> l = [('key1','value1'), ('key2','value2'), ('key3',3)]

>>> {k:v for k,v in l if isinstance(v, str)}  # Only add strings.
{'key1': 'value1', 'key2': 'value2'}

Any valid expression can be used for the comparison, as long as it returns thruthy or falsey values.

python

>>> l = [('key1','value1'), ('key2','value2'), ('key3',3)]

>>> {k:v for k,v in l if v != 'value1'}
{'key2': 'value2', 'key3': 3}

Comparisons can be performed against keys, values, or both.

python

>>> l = [('key1','value1'), ('key2','value2'), ('key3',3)]

>>> {k:v for k,v in l if v != 'value1' and k != 'key3'}
{'key2': 'value2'}

Since empty string evaluates as False in Python testing the value alone can be used to strip empty string values from a dictionary.

python

>>> d = {'key1':'value1', 'key2':'value2', 'key3':'', 'another-empty':''}

>>> {k:v for k,v in d.items() if v}
{'key1': 'value1', 'key2': 'value2'}

Separate lists of keys and values can be zipped, and filtered using a dictionary comprehension.

python

>> k = ['key1', 'key2', 'key3']
>> v = ['value1', 'value2', 3]

>>> {k:v for k,v in zip(k,v) if k != 'key1'}
{'key2': 'value2', 'key3': 3}

Expressions can also be used in the k:v construct to alter keys or values that are generated for the dictionary.

python

>>> l = [('key1', 1), ('key2', 2), ('key3', 3)]

>>> {k:v**2 for k,v in l}
{'key1': 1, 'key2': 4, 'key3': 9}

Any expressions are valid, for both keys and values, including calling functions.

python

>>> l = [('key1', 1), ('key2', 2), ('key3', 3)]

>>> def cube(v):
...     return v**3

>>> def reverse(k):
...     return k[::-1]

>>> {reverse(k):cube(v) for k,v in l}
{'1yek': 1, '2yek': 8, '3yek': 27}

You can use a ternary if-else in the k:v to selectively replace keys. In the following example values are replaced if they don't match 'value1'.

python

>>> l = [('key1','value1'), ('key2','value2'), ('key3',3)]

>>> {k:v if v=='value1' else None for k,v in l}
{'key1': 'value1', 'key2': None, 'key3': None}

You can also use ternary syntax to process keys. Any expressions are valid here, in the follow example we replace missing keys with the current iteration number (1-indexed).

python

>>> l = [(None,'value1'), (None,'value2'), ('key3',3)]

>>> {k if k else n:v for n,(k,v) in enumerate(l, 1)}
{1: 'value1', 2: 'value2', 'key3': 3}

If your expressions generate duplicate keys, the later value will take precedence for that key.

python

>>> l = [(None,'value1'), (None,'value2'), ('key3',3)]

>>> {k if k else 0:v for n,(k,v) in enumerate(l)}
{0: 'value2', 'key3': 3} # 0:value1 has been overwritten by 0:value1

You can use nested loops within dictionary comprehensions although you often won't want to since it can get pretty confusing. One useful application of this however is for flattening nested dictionaries. The follow example unnestes 2-deep dictionaries, discarding the outer keys.

python

>>> d = {'a': {'naa':1, 'nab':2, 'nac':3}, 'b': {'nba':4, 'nbb':5, 'nbc':6}}

>>> {k:v for di in d.values() for k,v in di.items()}
{'naa': 1, 'nab': 2, 'nac': 3, 'nba': 4, 'nbb': 5, 'nbc': 6}

The left hand loops it the outer loop, which iterates the d dictionary producing the values in di. The inner loop on the right iterates this dictionary keys and values as k and v, which are used to construct the new dictionary on the far left k:v.

Merging

There are a number of ways to merge dictionaries. The major difference between the approaches is in how (or whether) they handle duplicate keys.

Update

Each dictionary object has an .update() method, which can be used to add a set of keys and values to an existing dictionary, using another dictionary as the source.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key4':'value4', 'key5':'value5'}

>>> d1.update(d2)
>>> d1
{'key1':'value1', 'key2':'value2', 'key3': 3, 'key4':'value4', 'key5':'value5'}

This updates the original dictionary, and does not return a copy.

If there are duplicate keys in the dictionary being updated from, the values from that dictionary will replace those in the dictionary being updated.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.update(d2)
>>> d1
{'key1':'value1', 'key2':'value2', 'key3':'value3-new', 'key5':'value5'}

If you do not want to replace already existing keys, you can use a dictionary comprehension to pre-filter.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d1.update({k:v for k, v in d2.items() if k not in d1})
>>> d1
{'key1':'value1', 'key2':'value2', 'key3': 3, 'key5':'value5'}

Unpacking

Dictionaries can be unpacked to key=value keyword pairs, which is used to pass parameters to functions or constructors. This can be used to combine multiple dictionaries by unpacking them consecutively.

This requires Python 3.6 and above.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key4':'value4', 'key5':'value5'}

>>> d = {**d1, **d2}
>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 3, 'key4': 'value4', 'key5': 'value5'}

Unpacking using this syntax handles duplicate keys, with the later dictionary taking precedence of the earlier.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> d = {**d1, **d2}
>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 'value3-new', 'key5': 'value5'}

You can use this same syntax to merge multiple dictionaries together.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}
>>> d3 = {'key4':'value4', 'key6':'value6'}

>>> d = {**d1, **d2, **d3}
>>> d
{'key1': 'value1', 'key2': 'value2', 'key3': 'value3-new', 'key5': 'value5', 'key4': 'value4', 'key6': 'value6'}

You can also unpack to a dict()

python

>>> dict(**d1, **d3)
{'key1': 'value1', 'key2': 'value2', 'key3': 3, 'key4': 'value4', 'key6': 'value6'}

>>> dict(**d1, **d2)
TypeError: type object got multiple values for keyword argument 'key3'

However, in this case duplicate keys are not supported, and you are limited by the keyword naming restrictions described earlier.

python

>>> dict(**d1, **d2)
TypeError: type object got multiple values for keyword argument 'key3'

>>> dict(**{3:'value3'})
TypeError: keyword arguments must be strings

There is no such restriction for {} unpacking.

python

>>> {**{3:'value3'}}
{3:'value3'}

Addition (Python 2.7 only)

In Python 2.7 dict.items() returns a list of (key, value) tuples. Lists can be concatenated using the + operator, and the resulting list can be converted back to a new dictionary by passing to the dict constructor.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}

>>> l = dict(d1.items() + d2.items())
>>> l
[('key3', 3), ('key2', 'value2'), ('key1', 'value1'), ('key3', 'value3-new'), ('key5', 'value5')]

>>> dict(l)
{'key3': 'value3-new', 'key2': 'value2', 'key1': 'value1', 'key5': 'value5'}

You can add together multiple dictionaries using this method. The later dictionary keys take precedence over the former.

Union (set merge)

If both the keys and values of a dictionary are hashable, the dict_items view supports set-like operations.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5':'value5'}
>>> d3 = {'key4':'value4', 'key6':'value6'}

>>> dict(d1.items() | d2.items() | d3.items())
{'key4': 'value4', 'key5': 'value5', 'key2': 'value2', 'key6': 'value6', 'key3': 3, 'key1': 'value1'}

The merging occurs right-to left.

If the values are not hashable this will raise a TypeError.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}
>>> d2 = {'key3':'value3-new', 'key5': []}  # list is unhashable

>>> d1.items() | d2.items()
TypeError: unhashable type:'list'

All standard set operations are possible on dict_keys and dict_items.

Copying

To make a copy of an existing dictionary you can use .copy(). This results in an identical dictionary which is a distinct object.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> d2 = d1.copy()
>>> d2
{'key1':'value1', 'key2':'value2', 'key3':3}

>>> id(d1) == id(d2)
False

You can also make a copy of a dictionary by passing an existing dictionary to the dict constructor. This is functionally equivalent to .copy().

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':3}

>>> d2 = dict(d1)
>>> d2
{'key1':'value1', 'key2':'value2', 'key3':3}

>>> id(d1) == id(d2)
False

In both cases these are shallow copies meaning nested objects within the dictionary are not also copied. Changes to this nested objects will also be reflected in the original dictionary.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':{'nested':'dictionary'}}

>>> d2 = d1.copy()
>>> d2
{'key1': 'value1', 'key2': 'value2', 'key3': {'nested': 'dictionary'}}

>>> id(d1) == id(d2)
False

>>> id(d1['key3']) == id(d2['key3'])
True

>>> d2['key3']['nested'] = 'I changed in d1'
>>> d1
{'key1': 'value1', 'key2': 'value2', 'key3': {'nested': 'I changed in d1'}}

If you want nested objects to also be copied, you need to create a deepcopy of your dictionary.

python

>>> d1 = {'key1':'value1', 'key2':'value2', 'key3':{'nested':'dictionary'}}

>>> from copy import deepcopy
>>> d2 = deepcopy(d1)
>>> d2
{'key1': 'value1', 'key2': 'value2', 'key3': {'nested': 'dictionary'}}

>>> id(d1) == id(d2)
False

>>> id(d1['key3']) == id(d2['key3'])
False

>>> d2['key3']['nested'] = ['I did not change in d1']
>>> d1
{'key1': 'value1', 'key2': 'value2', 'key3': {'nested': 'dictionary'}}

Since a deepcopy copies all nested objects it is slower and uses more memory. Only use it when it's actually neccessary.

Driving I2C OLED displays with MicroPython — I2C monochrome displays with SSD1306

2018-08-25T08:00:00+00:00

These mini monochrome OLED screens make great displays for projects — perfect for data readout, simple UIs or monochrome games.

Requirements
Wemos D1 v2.2+ or good imitations.	amazon
0.91in OLED Screen 128x32 pixels, I2c interface.	amazon
Breadboard Any size will do.	amazon
Wires Loose ends, or jumper leads.

Setting up

MicroPython provides some built-in support for these displays, and a simple framebuffer which can be used as a drawing surface. However, we still need a driver to interface the buffer to the display.

There is a Python ssd1306 module for OLED displays available in the MicroPython repository. Click Raw format and save the file with a .py extension.

You can then use the ampy tool (or the WebREPL) to upload the file to your device's filesystem:

bash

ampy --port /dev/tty.wchusbserial141120 put ssd1306.py

With the ssd1306.py file on your Wemos D1, you can import it as any other Python module. Connect to your device, and then in the REPL enter:

python

from machine import I2C, Pin
import ssd1306

Both I2C and SPI-controlled displays are available — these instructions will only work for I2C displays.

If the import ssd1306 succeeds, the package is correctly uploaded and you're good to go. Wire up the OLED display, connecting pins D1 to SCL and D2 to SDA. Provide power from G and 5V.

Using the interface

The following instructions are based on a 0.91in monochrome 128x32 OLED, but other displays using the same chipset can be used with this library.

To use the display you first need to create an I2C interface. In MicroPython I2C is via a software implementation so you can put it on any GPIO pins you like.

python

i2c = I2C(-1, Pin(5), Pin(4))
display = ssd1306.SSD1306_I2C(128, 32, i2c)

The SSD1306 module makes use of the MicroPython framebuf frame buffer, an efficient in-memory buffer for working with a simple graphics view. The methods for drawing text and primitives are from this framebuffer implementation. For a complete overview of what's available, check the MicroPython documentation.

The setup of the framebuffer format (monochrome, bit ordering, etc.) is also handled by the SSD1306 library. Check the framebuf documentation for more info on available options for other displays.

To test your I2C connection to the display, fill the display in solid colour.

python

display.fill(1)  # Fill the entire display with 1="on"
display.show()

You need to call display.show() to actually send the current framebuf to the device.

Drawing primitives

The .fill() method can be used to fill the entire display with a specified colour. Note that this changes all pixels to the given colour, and does not perform a flood fill of matching regions.

python

# Fill the entire display with colour 0
display.fill(0)

For filling specific regions of the display see .fill_rect() below.

Setting individual pixels can be accomplished using .pixel(). This is only a good idea when you area setting relatively few pixels as it is much slower than using other methods.

python

# Set the pixel at 3, 4 (x, y) to 1
# .pixel(x, y, c)
display.pixel(3, 4, 1)  # 3rd param is the colour
display.show()

If you don't provide a color via parameter c, this method returns the colour of the pixel at the specified coordinates.

python

# Return the value at 3, 4 (x, y)
# .pixel(x, y)
c = display.pixel(3, 4)

This is not a particularly nice API. In other cases (e.g. text) omitting the optional c will use 1 as a default.

Horizontal and vertical lines can be drawn with .hline() and .vline() respectively, providing a starting x,y location and line length and colour.

python

# Draw a horizontal line, starting from 2, 3 (x, y), 4 pixels wide
# .hline(x, y, w, c)
display.hline(2, 3, 25, 1)
display.show()

python

# Draw a vertical line, starting from 5, 0 (x, y), 6 pixels high
# .vline(x, y, h, c)
display.vline(5, 0, 15, 1)
display.show()

For diagonal lines, the .line() method can be used to draw lines between between two sets of points x1,y1 and x2,y2 specified in order. The parameter c controls the colour of the line drawn.

python

# Draw a short diagonal line down to the right.
# .line(x1, y1, x2, y2, c)
display.line(0, 0, 50, 25, 1)
display.show()

There is no antialiasing, so diagonal lines will probably look pretty jaggy.

The .draw_rect() method allows you to draw a unfilled rectangle, starting at x,y and with a specified width w and height h. The specified colour c is used to draw the boundary of the rectangle, but it is not filled.

python

# Draw an unfilled rectangle of 8, 5 pixels, starting at 1,1 in colour 1.
# .rect(x, y, w, h, c)
display.rect(5, 5, 100, 20, 1)
display.show()

You can also draw filled rectangles, using .fill_rect(). The parameters are the same as for .rect() but all pixels within the boundary will be set.

python

# Draw a filled rectangle of 10x5 pixels, starting at 3,3 in colour 1
# .fill_rect(x, y, w, h, c)
display.fill_rect(9, 9, 25, 25, 1)
display.show()

Writing text

The framebuffer class provides support for writing text using a simple 8x8 bitmap font. The pixel x,y positions are relative to the top-left of the 8x8 character, so positioning at 0,0 will give the absolute top left of the screen.

python

# Print "Hello world!" 1 pixel from top left, in colour 1 (on)
# .text(text, x, y, c)
display.text("Hello world!", 1, 1, 1)
display.show()

The .text() method takes an optional 4th parameter color, which gives the colour to draw text in. On a mono screen this can be either 0 (off) or 1 (on).

python

# Print "Hello world!" at 2,2 in colour 0 (off)
display.text("Hello world!", 2, 2, 0)
display.show()

python

# Print "Hello world!" at 3,3 in colour 1 (on)
display.text("Hello world!", 3, 3, 1)
display.show()

Scrolling

You can shift the contents of the entire framebuffer around using .scroll, which takes x and y parameters to specify the scroll (positive/negative) in each dimension.

python

# .scroll(x, y)
display.scroll(-10, 0)

There is no support for scrolling a portion of the framebuffer. You can however keep a separate framebuffer which you scroll and then blit to your main display — see the next section.

Pixel graphics

For very simple graphics that do not update often you can get away with writing bitmap graphics to the framebuffer pixel by pixel. For example, in the following code block we draw an icon from a list-of-lists of binary colour data, iterating over with simple loops:

python

ICON = [
    [ 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [ 0, 1, 1, 0, 0, 0, 1, 1, 0],
    [ 1, 1, 1, 1, 0, 1, 1, 1, 1],
    [ 1, 1, 1, 1, 1, 1, 1, 1, 1],
    [ 1, 1, 1, 1, 1, 1, 1, 1, 1],
    [ 0, 1, 1, 1, 1, 1, 1, 1, 0],
    [ 0, 0, 1, 1, 1, 1, 1, 0, 0],
    [ 0, 0, 0, 1, 1, 1, 0, 0, 0],
    [ 0, 0, 0, 0, 1, 0, 0, 0, 0],
]

display.fill(0) # Clear the display
for y, row in enumerate(ICON):
    for x, c in enumerate(row):
        display.pixel(x, y, c)

display.show()

Using urandom we can scatter images over the display, like in the following example:

python

import urandom

def random_heart():
    xofs = urandom.getrandbits(8)
    yofs = urandom.getrandbits(5)
    for y, row in enumerate(ICON):
        for x, c in enumerate(row):
            display.pixel(x + xofs, y + yofs, c)

for n in range(100):
    random_heart()

display.show()

If you can add an if c around the display.pixel call to only output pixels which are on — effectively masking, and avoiding the black square.

For bigger graphics or where you need faster updates, you can instead blit your bitmap images from one framebuffer to another. Pass the framebuf to blit, and the coordinates x and y to blit at.

python

# Blit a framebuffer at the pixel position 1, 1.
# display.blit(fbuf, x, y)
display.blit(fbuf, 1, 1)

The blit method takes an optional 4th parameter key which is a colour to considered 'transparent' when blitting. Pixels with this value won't be copied over onto the target display.

python

# Blit except pixels with value 0 (i.e. only pixels with value 1)
# .blit(fbuf, x, y, key)
display.blit(fbuf, 1, 1, key=0)

See this follow up for details on how to display images on OLED screens, including animated graphics.

Display control

The drawing methods so far are inherited from the the MicroPython framebuf object, which is written to the display on .update(). But the ssd1306 object itself also provides methods for direct control of the display component.

The display can be turned on and off using display.poweron() and display.poweroff() respectively.

You can set the contrast for the display using .contrast() passing in parameter c which is a value between 0 and 255. This controls the contrast between the foreground, active colour 1 and the background 0.

python

# Set the display contrast to half (127/255 = 0.5)
# .contrast(c)
display.contrast(50)

To invert the display, switching foreground and background colours, call .invert(1).

python

display.invert(1)

Calling .invert(0) will return the display to how it was originally. You can use this for display-flashing visual effects:

python

import time
while True:
    display.invert(0)
    time.sleep(0.01)
    display.invert(1)
    time.sleep(0.01)

Turning a Lucky Cat into a Persistence of Vision display — Python-powered Maneki-neko persistence of vision scroller

2018-05-14T06:00:00+00:00

This build started as something simple: a lucky cat which would turn on and off automatically in response to some event. Since lucky cats are associated with good fortune the idea was to make one do this every time I got paid. This was working pretty well but unfortunately, after some over-zealous poking I managed to completely knacker the internals.

What you see below is the result of asking ...what else can I do with a gold cat?

If you can't see the video above, you can see a still here.

The display uses the persistence of vision effect to generate an image 'in the air'. By repeatedly outputting light at a specific point in the rotation, and with a short enough cycle time, the viewer's eye does not register any change in brightness.

The flicker in the video is caused by the camera running at 30fps and is less apparent in person.

Managing to generate a static image depends on hitting the exact same point on the next turn around the loop. By adding a slight over- or under-scan you can make the message display rotate.

Requirements
Lucky Cat Large enough to hold your other components.	amazon
Wemos D1 v2.2+ or good imitations.	amazon
L293D IC Motor driver chip.	amazon
3-6V motor Select depending on power requirements for your construction.	amazon
5x 100Ω resistors Ohms depends on chosen SMD.	amazon
5x SMD LEDs Adjust resistor Ω to match.	amazon
Optional: Sockets for D1 & L293D IC If you want to be able to remove them from the board.	amazon
Slip ring 6-wire rotating connection.	amazon
Protoboard Only need a bit.	amazon
4xAA battery pack Or whatever your motor needs.	amazon
Wires Loose ends, or jumper leads.
Bit of wood 40mm x 40mm x 45mm.
Zip ties To hold the motor on.
Glue Lots of glue.
Dremel or other rotary tool To make holes for the axle & wires.	amazon

The build is described below in parts, including the construction of the motor mechanism, the LED display and the driver board. If you just want the code, jump to the end. There should be enough detail here to hack together your very own lucky message cat!

The cat

Lucky cats are available to buy quite cheaply and come in various versions and colours. The model I ended up with seems quite common and is recommended, since it has a lot of working room inside.

The shell is made entirely of moulded plastic, with a gold sheen. The plastic is flexible, apart from where the shape gives it structural strength. However, the gold colour is very susceptible to solvents in glues. My cat ended up quite patchy by the time I was finished with it.

POOP: Despite appearances this is not a picture of the inside of my colon.

Motor support

The original mechanism inside a lucky cat uses an electromagnetic coil coupled with a small controller circuit powered by a single 1.5V battery. The arm is attached to a horizontal beam off which a magnet is suspended on a pendulum. The arm rocking mechanism rests inside on top of 4 legs, which we will use to hold our axel mount (a block of wood). The existing mechanism can be unscrewed from the top by removing the 4 tiny screws via the holes in the base.

There wasn't a simple way to make use of the mount to hold a motor, so I replaced it outright with a block of wood 40mm x 40mm x 45mm.

To position the axle the block was screwed onto the top of the mechanism legs, using the same screws, and then reassembled the cat. The axle was positioned to be in the middle of the arm hole, marked with a pencil and then drilled through on a drill press.

When drilling the axle hole pick a size which is as close-as but slightly wider than the diameter of your axle. Too wide will give wobble, too narrow and it'll get stuck.

Motor mechanism

The gears, axle and arm-mount connector I used for this build were all taken from the remains of the tank chassis used in the KropBot Mk I. This is a pretty inefficient way to get parts, and you can find better axle and gear parts bundles online. The axle needs to be about 65-75mm long.

The 3-6V motor sits on top of the mounting block and is then fastened into place with loops of zip ties. A couple of loops was enough to hold it in place, but still allow for manual adjustment.

Because of the gears available the motor could sit directly above the axle gear. A small offset backwards gave it enough space for the gears to mesh, but then the motor gear bumped the inside of the shell. I had to trim the motor axle down with a rotary tool to get it to fit.

Depending on whether you offset the motor forward or backward, it might run easier forwards or backwards. Bear that in mind later.

To allow power for the LEDs to be transferred across the rotating joint, I used a slip ring. The ones I bought were pretty chunky and to be able to get them inside the cat they needed to be recessed into the support block. The simplest way to do this was cut a chunk out of it. The slip ring was then screwed onto the block for support. After reassembling the cat a few times it was lined up enough to work.

While adjusting the block I screwed up my measurement and lopped off a bit too much. I then made things worse by using balsa to build it back up — balsa is too weak for the screws to hold it. Copious amounts of glue was the only answer.

Use more glue.

Once I was convinced everything lined up, the gear mechanism was disassembled and everything covered in silicone grease. Then it was reassembled, zip-tied and had the crap glued out of it.

To fix (some of) the wobble rotating at full speed I packed some folded paper into the space between the axle and the rotating inner ring of the slip ring. With this in place the rotation of the arm pulls the slip-ring with it, and the arm doesn't pull the axle up and down so much. It's not great, but it helps things a little.

Circuit

The complete schematic for the motor & LED driver circuit for our message cat is shown below.

The motor driver circuit is based on an L293D. The L293D is a 16 pin DIP containing two independent H-bridges circuits for dual-motor dual-direction control. Here we're only using a single motor, and usually only drive it in a single direction, so it's a bit of overkill — but it's what I had in my box. The inputs and outputs for each motor are on either side of the package, and there are 2 input pins, 2 output pins and 1 enable pin for each motor.

Pin	Function	Notes
1	Enable 1 & 2	HIGH to enable motor outputs 1 & 2 (left side)
2	Input 1	HIGH to drive current through output 1
3	Output 1	Connect to terminal 1 of Motor A
4,5	GND	Common ground for motor & IC, act as heatsink
6	Output 2	Connect to terminal 2 of Motor A
7	Input 2	HIGH to drive current through output 2
8	VCC Motor	Motor supply, from batteries
16	VCC IC (+5V)	IC supply, from microcontroller
15	Input 4	HIGH to drive current through output 4
14	Output 4	Connect to terminal 2 of Motor B
13,12	GND	Common ground for motor & IC, act as heatsink
11	Output 3	Connect to terminal 1 of Motor B
10	Input 3	HIGH to drive current through output 3
9	Enable 3 & 4	HIGH to enable motor outputs 3 & 4 (right side)

The IC can handle heavy currents and may generate a lot of heat. The 4 grounding pins are provided as a simple way to shed some of this heat, by acting as a basic heatsink. Make sure to solder them all to the board.

Since DC motors are inductive loads, and can generate back current when drive power is stopped or reversed. This voltage fluctuation could potentially damage the IC so a small ceramic capacitor is used to dampen this.

LEDs

The display uses 5 LEDs to give a reasonable, minimal horizontal resolution for text display. This was helpfully also about the right width using SMD LEDs and matched the number of wires available on the slip ring (6; 5 +ve, 1 GND). The vertical size of characters is entirely independent, as it is generated as the arm rotates.

It might be possible to fit more SMDs horizontally if you're good at soldering, but you'll need to get a different slip ring and get a different font.

Wiring

In the initial build the arm was connected by a screw adapter, taken from the cat's original arm mount. With this setup the wires had to enter the arm from the 'outside', and a small hole was drilled in the base of the arm for the wires to feed in. This was replaced after the attachment failed (see later).

I drilled a second hole at the knuckle, and the 6 wires were taped together and pushed up and out.

Board

Five red SMD LEDs were soldered on a small chunk of protoboard. I used red for the appearance, but white LEDs would be considerably brighter. The power wires were soldered from behind, and then the LEDs soldered on top. This wasn't ideal, and they ended up not exactly parallel, but it meant the wires could be kept out of view.

There were a few different ways to mount the LED display board on the hand, but I opted to cut a larger hole and recess them into it. Cutting the hole to fit as closely as possible and then relying on glue to make it stay in place. It's a bit of a mess up close, but not noticeable from a distance or when rotating.

Control

Because there are only 5 LEDs the control can be handled directly by GPIO pins. This keeps the control circuit for those very simple, with just resistors in series. The photo below shows the LEDs wired up to GPIO pins on the Wemos D1 with all pins HIGH.

For a quick test run, I wired the Wemos D1 and LEDs up using a breadboard and wrote a quick script to iterate over an array of values spelling out POOP — a palindrome, so it doesn't matter which way the arm spins.

Fiddling with the speed showed there was a good bit of leeway for generating messages of different lengths, and I could tune the output so the LEDs landed on the same point (or thereabouts) on each rotation. You can see from the blur on the mounting block that this was shaking quite a bit at the time — the final version runs the arm quite a bit slower so it doesn't try and get airborne.

Driver board

The goal for the driver board itself was to be able to slot the board in under the main gear, with enough clearance for it to rotate cleanly. The board was wired up on a small chunk of protoboard — wide enough to fit the D1 across the board, with space below for the L293D. Resistors were mounted under the D1 to save vertical space.

The completed & cropped control board, with motor drive wires (thick purple, thick yellow), LED driver wires (thin 5 colours) and motor power in (thick red, thick black). The underside is a bit messier than it should be as I stupidly tried to rework the L293D wiring in the process of moving from the breadboard. Thankfully I didn't release any magic smoke.

Don't be me. If you need to change something, re-prototype on the breadboard first.

With the wiring in place, I did a quick test everything with the control board to ensure everything was working as expected. After fixing a few dodgy solder joints, all the LEDs lit and the motor could turn both ways.

The control board mounted with screws onto the side of the motor mount. It landed just short of where the drive cog, leaving it free to rotate without needed any adjustment.

Assembly & final bodges

Unfortunately the combined height of the D1 on top of the control board and motor mount was too large to fit through hole in the bottom of the cat shell.

The shell was pared back with a craft knife until it fit. The motor mount rotated up and around until it poked out the arm hole. I also had to trim the motor drive shaft with a dremel as it was pressing against the inside.

The hole in the back of the cat — from previous misadventures — was taped up to get rid of sharp edges. This is where the USB power lead enters to power the D1, the motor wires (seen in the photo below) actually exit via the base to the AA battery pack.

The photo below shows the wires for the LEDs in the original arrangement where they enter the base of the arm. They knocked against the shell while rotating making an annoying knocking sound. I was looking for ways to fix this, when the mount-lock on the end of the arm cracked open presenting a solution: more glue. The mount was cut off, the wires moved to the inside and the arm pushed over the mount, then glued in place.

The final step was to mount the cat on top of a battery pack — for stability/weight as well as power. The bottom of the battery case was also affixed to the table with velcro pads, to minimise the shaking while taking photo & video of it running.

Code

The display code needs to do a few things —

Get the arm spinning at a fast enough speed but not so fast we can't get text out in time. The speed should be constant(-ish).
Turn the LEDs on and off, as close to row-by-row as possible, to generate characters as the arm rotates. Using a font with max 5-pixel width.
Time both the above so that each time the arm rotates the display of text happens in roughly the same place as the last rotation.

With all of those in place, we should have a functional persistance-of-vision LED display for short messages. Below is breakdown of the code I used to achieve this on my lucky cat.

Character Set

For the text we're using a simple 5x7 pixel display font, based on Adafruit's glcdfont.c. This has been converted to Python list of tuple structure. The character set is in ASCII order, including the first 128 symbols. A few custom symbols were added on top, including —

Code	Symbol	Bytes
128	Heart	0x0c, 0x1e, 0x3c, 0x1e, 0x0c
129	Python	0x18, 0x3a, 0x3e, 0x2e, 0x0c
130	Aubergine	0x1c, 0x3e, 0x7f, 0x73, 0x66
131	Poop	0x40, 0x71, 0x78, 0x62, 0x40
132	Cat	0x3c, 0x57, 0x4c, 0x57, 0x3c

You can generate your own custom characters using this tool. Make sure to select column major and little endian. There is no width 5 option, or height 7 option. Use 6 & 8 and keep to the top left. After generating copy the first 5 values only.

Each character is represented by a tuple of 5 int values (with byte range 0-255) covering the 5 pixel width. The binary representation of each of these values determines whether a given pixel is on/off vertically down the character.

This wastes a lot of memory, but keeps the later code simple.

python

CHARSET = [
    (0, 0, 0, 0, 0),
    (62, 91, 79, 91, 62),
    (62, 107, 79, 107, 62),
    (28, 62, 124, 62, 28),
    (24, 60, 126, 60, 24),
    (28, 87, 125, 87, 28),
    (28, 94, 127, 94, 28),
    (0, 24, 60, 24, 0),
    (255, 231, 195, 231, 255),
    (0, 24, 36, 24, 0),
    (255, 231, 219, 231, 255),
    (48, 72, 58, 6, 14),
    (38, 41, 121, 41, 38),
    (64, 127, 5, 5, 7),
    (64, 127, 5, 37, 63),
    (90, 60, 231, 60, 90),
    (127, 62, 28, 28, 8),
    (8, 28, 28, 62, 127),
    (20, 34, 127, 34, 20),
    (95, 95, 0, 95, 95),
    (6, 9, 127, 1, 127),
    (0, 102, 137, 149, 106),
    (96, 96, 96, 96, 96),
    (148, 162, 255, 162, 148),
    (8, 4, 126, 4, 8),
    (16, 32, 126, 32, 16),
    (8, 8, 42, 28, 8),
    (8, 28, 42, 8, 8),
    (30, 16, 16, 16, 16),
    (12, 30, 12, 30, 12),
    (48, 56, 62, 56, 48),
    (6, 14, 62, 14, 6),
    (0, 0, 0, 0, 0),        # 32: space
    (0, 0, 95, 0, 0),
    (0, 7, 0, 7, 0),
    (20, 127, 20, 127, 20),
    (36, 42, 127, 42, 18),
    (35, 19, 8, 100, 98),
    (54, 73, 86, 32, 80),
    (0, 8, 7, 3, 0),
    (0, 28, 34, 65, 0),
    (0, 65, 34, 28, 0),
    (42, 28, 127, 28, 42),
    (8, 8, 62, 8, 8),
    (0, 128, 112, 48, 0),
    (8, 8, 8, 8, 8),
    (0, 0, 96, 96, 0),
    (32, 16, 8, 4, 2),
    (62, 81, 73, 69, 62),   # 48: 0
    (0, 66, 127, 64, 0),
    (114, 73, 73, 73, 70),
    (33, 65, 73, 77, 51),
    (24, 20, 18, 127, 16),
    (39, 69, 69, 69, 57),
    (60, 74, 73, 73, 49),
    (65, 33, 17, 9, 7),
    (54, 73, 73, 73, 54),
    (70, 73, 73, 41, 30),
    (0, 0, 20, 0, 0),
    (0, 64, 52, 0, 0),
    (0, 8, 20, 34, 65),
    (20, 20, 20, 20, 20),
    (0, 65, 34, 20, 8),
    (2, 1, 89, 9, 6),
    (62, 65, 93, 89, 78),
    (124, 18, 17, 18, 124), # 65: A
    (127, 73, 73, 73, 54),
    (62, 65, 65, 65, 34),
    (127, 65, 65, 65, 62),
    (127, 73, 73, 73, 65),
    (127, 9, 9, 9, 1),
    (62, 65, 65, 81, 115),
    (127, 8, 8, 8, 127),
    (0, 65, 127, 65, 0),
    (32, 64, 65, 63, 1),
    (127, 8, 20, 34, 65),
    (127, 64, 64, 64, 64),
    (127, 2, 28, 2, 127),
    (127, 4, 8, 16, 127),
    (62, 65, 65, 65, 62),
    (127, 9, 9, 9, 6),
    (62, 65, 81, 33, 94),
    (127, 9, 25, 41, 70),
    (38, 73, 73, 73, 50),
    (3, 1, 127, 1, 3),
    (63, 64, 64, 64, 63),
    (31, 32, 64, 32, 31),
    (63, 64, 56, 64, 63),
    (99, 20, 8, 20, 99),
    (3, 4, 120, 4, 3),
    (97, 89, 73, 77, 67),
    (0, 127, 65, 65, 65),
    (2, 4, 8, 16, 32),
    (0, 65, 65, 65, 127),
    (4, 2, 1, 2, 4),
    (64, 64, 64, 64, 64),
    (0, 3, 7, 8, 0),
    (32, 84, 84, 120, 64),  # 97: a
    (127, 40, 68, 68, 56),
    (56, 68, 68, 68, 40),
    (56, 68, 68, 40, 127),
    (56, 84, 84, 84, 24),
    (0, 8, 126, 9, 2),
    (24, 164, 164, 156, 120),
    (127, 8, 4, 4, 120),
    (0, 68, 125, 64, 0),
    (32, 64, 64, 61, 0),
    (127, 16, 40, 68, 0),
    (0, 65, 127, 64, 0),
    (124, 4, 120, 4, 120),
    (124, 8, 4, 4, 120),
    (56, 68, 68, 68, 56),
    (252, 24, 36, 36, 24),
    (24, 36, 36, 24, 252),
    (124, 8, 4, 4, 8),
    (72, 84, 84, 84, 36),
    (4, 4, 63, 68, 36),
    (60, 64, 64, 32, 124),
    (28, 32, 64, 32, 28),
    (60, 64, 48, 64, 60),
    (68, 40, 16, 40, 68),
    (76, 144, 144, 144, 124),
    (68, 100, 84, 76, 68),
    (0, 8, 54, 65, 0),
    (0, 0, 119, 0, 0),
    (0, 65, 54, 8, 0),
    (2, 1, 2, 4, 2),
    (60, 38, 35, 38, 60),

    # Custom symbols.
    (0x0c, 0x1e, 0x3c, 0x1e, 0x0c), # Heart
    (0x18, 0x3a, 0x3e, 0x2e, 0x0c), # Python
    (0x1c, 0x3e, 0x7f, 0x73, 0x66), # Aubergine
    (0x40, 0x71, 0x78, 0x62, 0x40), # Poop
    (0x3c, 0x57, 0x4c, 0x57, 0x3c), # Cat
]

Using the above character table, outputting each character as we rotate the arm would require us to convert each column to binary, select the current vertical position from this, and toggle LED based on the value (0 or 1). Rotating at full-whack this is quite a lot to accomplish. If it takes a long time to calculate each row the characters become very large (as the arm rotates while it is happening). If the inter-pixel delay is too large, the characters become distorted.

To move as much delay out of the display loop as possible, we can pre-process the character data for a given message and convert it into a straight pixel-array. This eliminates the conversion and lookup from the display loop, turning into a simple iteration.

We could speed this up even more using an external shift register. Each row would be drawn by sending a single byte to the register to update all LEDs in a single operation.

python

def build_message_display(message, length):
    result = []
    for char in reversed(message):
        glyph = CHARSET[ord(char)]
        build = []
        for line in glyph:
            build.append([1 if c == '1' else 0 for c in "{0:07b}".format(line)])

        for y in range(7):
            result.append([build[x][y] for x in range(5)])

        # Blank line between letters
        result.append([0,0,0,0,0])
        result.append([0,0,0,0,0])

    # Pad to the vertical resolution of the display.
    text_len = len(result)
    if text_len < length:
        for _ in range(length-text_len):
            result.append([0,0,0,0,0])

    return result

Setup

For the display we create 5 output pins, one for each LED, and arranged in a list LEDS so we can iterate over them easily in the display code. We also need to setup the output pin to control the LS motor driver. We only actually use Pin(4) since the arm needs to rotate in one direction only. A PWM object is created and set to 30Hz duty cycle.

This duty cycle was selected by experimentation. At 30Hz the motor speed is stable enough to not affect the display, and provides a kick long enough to get the motor started against the mechanical resistance at standstill.

python

from machine import Pin, PWM
import time

p1 = Pin(15, Pin.OUT)
p2 = Pin(13, Pin.OUT)
p3 = Pin(12, Pin.OUT)
p4 = Pin(14, Pin.OUT)
p5 = Pin(16, Pin.OUT)

LEDS = [p1,p2,p3,p4,p5]

m1 = Pin(4, Pin.OUT)
m1.off()

# Use this if you want the arm to go the other way.
# m2 = Pin(0, Pin.OUT)
# m2.off()

motor = PWM(m1)

motor.freq(30)
motor.duty(0)

Display

The final code is our display() method, which we use to display a message. Optional parameters for duration, duty and length need to be tweaked for a given cat, since the max display length depends on how long a rotation takes and the required duty cycle for a given rpm is affected by mechanical weirdness.

The default values work for my cat, giving a message which is relatively static visually, with a slight rotation upwards (the right way).

python

def display(message, duration=1000, duty=585, length=101):
    motor.duty(duty)

    dispm = build_message_display(message, length)

    for n in range(duration):

        for line in dispm:
            for p, v in zip(LEDS, line):
                p.on() if v else p.off()
            time.sleep(0.001)

    motor.duty(0)

The length parameter is the maximum length of message which can be displayed, and is also the length to which any message is padded with space. To display longer messages we could rotate a window over the generated dispm, but this would need some sort of rotation sync detection to ensure the split doesn't end at the front.

Complete

The video below shows the cat in action, displaying a long-running message including some custom characters. It looks pretty neat.

Retrospective

This poor cat was been hacked, poked, cut, drilled, sanded and left with a gaping hole in it's back. The motor mechanism was slightly too large and had to be bodged to fit with a wedge on the base, and the axle is slightly misaligned amplifying the wobble. If the alignment and weight distribution was better it might not need to be Velcro'd down while running. It might also sound less like a blender — though that could be wishful thinking.

There is quite a bit of space inside the cat (particularly the head). I reckon with a bit better planning I could fit the entire mechanism, batteries and a power supply for the D1 in there. This would allow the unit to run standalone disconnected from power. But that will have to wait til I get a 3D printer for the parts.

Martin Fitzpatrick - python

6th Edition - Create GUI Applications with Python & Qt, Released — PyQt6 & PySide6 Books updated for 2025 with model view controller architecture, new Python/Qt features and more examples

PyQt6 Book now available in Korean: 파이썬과 Qt6로 GUI 애플리케이션 만들기 — The hands-on guide to creating GUI applications with Python gets a new translation

Getting Started With Git and GitHub in Your Python Projects — Version-Controlling Your Python Projects With Git and GitHub

Installing and Setting Up Git

Understanding How Git Works

Version-Controlling a Project With Git: The Basics

Initializing a Git Repository

Checking the Status of Our Project

Tracking and Committing Changes

Using a .gitignore File to Skip Unneeded Files

Working With Branches in Git

Creating New Branches

Checking Out to a New Branch

Merging Two Branches Together

Deleting Unused Branches

Using a GUI Client for Git

Managing a Project With GitHub

Setting Up a Secure Connection to GitHub

Creating and Setting Up a GitHub Repository

Pushing a Local Git Repository to GitHub

Pulling Content From a GitHub Repository

Exploring Alternatives to GitHub

Conclusion

Working With Classes in Python — Understanding the Intricacies of Python Classes

Defining Classes in Python

Adding Class and Instance Аttributes

Providing Behavior With Methods

Writing Getter & Setter Methods

Writing Special Methods

Reusing Code With Inheritance

Wrapping Up Classes-Related Concepts

Conclusion

Getting started with VS Code for Python — Setting up a Development Environment for Python programming

Setup a Python environment

Setup Visual Studio Code

Usage and Configuration

Linting and Formatting Support (Optional)

Working With Virtual Environments

Understanding Workspaces in VS Code

Working With Git in VS Code (Optional)

Community-driven & open source alternatives

Conclusion

PyQt6, PySide6, PyQt5 and PySide2 Books -- updated for 2022! — New editions extended and updated, now 780+ pages

DiffCast: Hands-free Python Screencast Creator — Create reproducible programming screencasts without typos or edits

PySide6 tutorial now available — Complete course, updated for PySide2 & PySide6

Getting started creating Python GUIs with PySide

Using Qt Designer with PySide

Extended UI features in PySide

Multi threading PySide applications & QProcess

Qt Model Views

Pyside plotting & graphics with Matplotlib/PyQtGraph

Bitmap graphics and custom widgets

Packaging (PySide2 only)

PyQt6 Book now available: Create GUI Applications with Python & Qt6 — The hands-on guide to making apps with Python

PySide6 Book now available: Create GUI Applications with Python & Qt6 — The hands-on guide to making apps with Python

Using MicroPython and uploading libraries on Raspberry Pi Pico — Using rshell to upload custom code

Installing rshell

The rshell interface

Connecting to your Pico with rshell

Starting a REPL

Uploading a file

Using uploaded libraries

Auto-running Python

What's next?

Writing a SAM Coupé SCREEN$ Converter in Python — Interrupt optimizing image converter

Sam Coupe Screen Modes

The SCREEN$ format

Palette A & B

MODE 3 Store

Interrupts

Converting Image to SCREEN$

Pre-processing

Interrupts

SAM Coupé Palette

Packing bits

Writing the SCREEN$

Examples

Converting SCREEN$ to Image

Squeezing Space Invaders onto the BBC micro:bit's 25 pixels — MicroPython retro game in just 25 pixels

Using a `.gitignore` File to Skip Unneeded Files

All keys (`set` union)

Keys in common (`set` intersection)

Unique keys (`set` difference)

Unique keys from both (`set` symmetric difference)

Merge (`set` union)

Common entries (`set` intersection)

Unique entries (`set` difference)

Unique entries from both (`set` symmetric difference)