Martin Fitzpatrick

Remaking the classic Atari game ET in 10 lines of SAM Coupé BASIC

2021-02-07T09:00:00+00:00

The Basic 10 Liner contest has been running for 11 years. This year (2021) the 10th competition, and the first time I've heard of it, thanks to Dean Belfield.

The competition is simple: write a game in some BASIC language in 10 lines of code. Like the arcade games for the micro:bit the fun comes from trying to squeeze as much of a game as possible out of impossible limits.

Since many BASIC dialects allow you to stack multiple statements onto the same line (SAM BASIC is no exception) there are additional category limits on characters per line, e.g.

Category "PUR-80": Program a game in 10 lines (max 80 characters per logical line, abbreviations are allowed).
Category "PUR-120": Program a game in 10 lines (max 120 characters per logical line, abbreviations are allowed)

After finishing my first attempt Snake in 80 char lines, I wanted to have a go at something a little more complex under the PUR-120 category. I chose a remake of the Atari "Classic" ET: the Extra Terrestrial.

Complete playthrough video, with win

Playing

You control ET using the keys Q, A, O & P. The objective is to collect all the bits of phone and then escape in the rocket. Bits of phone are hidden in pits on the map, which you need to explore. To explore a pit, move over it and press SPACE. Explored pits are cleared from the map.

Trying to stop you are 3 agents which follow you around. They can move more quickly over diagonals and will get more desperate as you collect more pieces of the phone, getting faster. Once you have 5 bits of phone the rocket will appear, and you must race to get there before the agents catch you.

The game is hard, but completable (see the included GIF). The trick is to choose carefully the order of the pits you clear and use the agents behaviour on diagonals to herd them out of the way.

You can download a disk image containing Snake and ET from here. To play, you can use the SimCoupe emulator. Insert disk image with File>Open. Load & Run with LOAD "et" LINE 1. Press ESC to break to source.

Readable code

The complete code is shown below with inline comments.

basic

# vars x, y: current coords
#      p: number of parts collected
#      o: holds memory address &8000 (start of pits x, y)
#      b: holds o+10 (start of agents x, y)
#      c: memory location of user defined graphic 150
LET o=&8000,c=UDG CHR$ 150,b=o+10,x=10,y=10,p=0:

# Poke the pit locations (10 bytes) and agent locations (6 bytes) to memory
POKE o,5,5,15,5,26,5,11,15,19,15,4,4,18,6,10,7:

# Poke the custom character graphics to memory.
POKE c,0,124,124,96,50,20,124,126       # ET character
POKE c+8,0,60,126,255,255,126,60,0      # hole
POKE c+16,24,60,60,60,126,60,102        # rocket
POKE c+24,24,60,24,27,62,24,24,24       # agent
POKE c+32,112,120,24,24,88,56,24,60     # telephone / space dildo

# Set the background colour to a calm green.
PALETTE 0, 65

# Built in SAM Coupe sound effect.
ZAP

# Main loop
DO
    LET i$=INKEY$

    # Clear the players current location.
    PRINT AT y,x;" "
    IF i$="q":LET y=y-1: ELSE IF i$="a": LET y=y+1: ELSE IF i$="o": LET x=x-1: ELSE IF i$="p": LET x=x+1: END IF

    # Constrain positions to map.
    LET x=x MOD 31
    LET y=y MOD 18

    # Draw the new location.
    PRINT AT y,x; PEN 7;CHR$ 150

    # Handle agents.
    FOR k=0 TO 2

        # Get this agents location from memory.
        LET bx=PEEK (b+k*2), by=PEEK (b+k*2+1)

        # Random number 0-7, if less than the number of pieces move. As the player collects
        # more pieces, this evaluates to TRUE more frequently.
        IF RND(7)<=p
            PRINT AT by,bx;" "

            # Calculate diff to player, as a -1..+1 delta, update.
            LET xd=(x-bx), bx=bx+xd DIV ABS xd: LET yd=(y-by), by=by+yd DIV ABS yd

            # Put the new location back in memory.
            POKE (b+k*2),bx,by
        END IF

        # Draw the agent in black.
        PEN 8: PRINT AT by,bx;CHR$ 153

        # If the agent has hit the player, exit: game over.
        EXIT IF bx=x AND by=y

    NEXT k

    # Handle the holes.
    FOR k=0 TO 4

        # Get hole's x & y location from memory.
        LET hx=PEEK (o+k*2), hy=PEEK (o+k*2+1)

        # hx is 0 if the hole has been explored.
        IF hx
            # Draw the pit (PEN will still be 8 from the agents).
            PRINT AT hy,hx; CHR$ 151

            # h=(x=hx AND y=hy) means h=TRUE if the player is over this hole.
            LET h=x=hx AND y=hy

            # If the player is over the hole and pressing Space
            IF i$=" " AND h

                # Erase the hole's coords (we could just wipe the x)
                POKE (o+k*2), 0,0

                # Increase the parts count and make a ZAP noise.
                LET p=p+1: ZAP

                # Draw the space dildo.
                PRINT AT 18,p; PEN 11;CHR$ 154:

            END IF

        END IF
    NEXT k

    # If the players got 5 parts.
    IF p=5
        # Draw the rocket.
        PEN 10: PRINT AT 10,20;CHR$ 152

        # If the player is standing on the rocket.
        IF x=20 AND y=10

            # Draw a rocket launch.
            FOR ry=1 TO 10
                # Draw rocket (red), backspace, line feed, * (yellow)
                PRINT AT 10-ry,20;PEN 10;CHR$ 152;CHR$ 8;CHR$ 10;PEN 14;"*"

                # Sound effect
                POW
            NEXT ry

            # Exit the game, won!
            EXIT IF 1

        END IF
    END IF
LOOP

# Both EXIT IF calls end here, Restart
RUN

The sprites are drawn using User Defined Graphics the SAM's custom character graphics. Each character is 8x8 monochrome (1 bpp) and can be poked to memory directly as a series of 8, 1 byte values. The expression UDG CHR$ 150 returns the memory address of the character in code position 150. Poking 8 bytes to this address will replace that character.

PUR 120

To squeeze the game down to fit the 120 character line limit I used the following tricks.

Use MOD 18 and MOD31 to wrap the player position, rather than comparisons.
Use MOD, ABS and DIV to calculate the move for the agents.
The &8000 address was stored in a variable o saving 4 chars each, or 2 for o+1, o+2.
Specific ordering of each loop block (originally the draw order was different).
Statements were folded back into lines using :, including breaking IF and ELSE blocks across lines. SAM BASIC doesn't care about line grouping.
The EXIT IF 1 is redundant, we could just use RUN, but the earlier EXIT IF bx=x AND by=y would become IF bx=x AND by=y: RUN: END IF (+8 chars) overflowing that line.

basic

1LET o=&8000,c=UDG CHR$150,b=o+10,x=10,y=10,p=0:POKE o,5,5,15,5,26,5,11,15,19,15,4,4,18,6,10,7:PALETTE 0, 65:ZAP
2POKE c,0,124,124,96,50,20,124,126:POKE c+8,0,60,126,255,255,126,60,0:POKE c+16,24,60,60,60,126,60,102
3POKE c+24,24,60,24,27,62,24,24,24:POKE c+32,112,120,24,24,88,56,24,60:DO:LET i$=INKEY$:PRINT AT y,x;" ":IF i$="q"
4LET y=y-1:ELSE IF i$="a":LET y=y+1:ELSE IF i$="o":LET x=x-1:ELSE IF i$="p":LET x=x+1:END IF:LET x=x MOD 31
5LET y=y MOD 18:PRINT AT y,x; PEN 7;CHR$150:FOR k=0 TO 2:LET bx=PEEK (b+k*2), by=PEEK (b+k*2+1):IF RND(7)<=p
6PRINT AT by,bx;" ":LET xd=(x-bx),bx=bx+xd DIV ABS xd:LET yd=(y-by),by=by+yd DIV ABS yd:POKE (b+k*2),bx,by:END IF
7PEN 8:PRINT AT by,bx;CHR$153:EXIT IF bx=x AND by=y:NEXT k:FOR k=0 TO 4:LET hx=PEEK (o+k*2), hy=PEEK (o+k*2+1)
8IF hx:PRINT AT hy,hx; CHR$151:LET h=x=hx AND y=hy:IF i$=" " AND h:POKE (o+k*2), 0,0:LET p=p+1:ZAP
9PRINT AT 18,p; PEN 11;CHR$154:END IF:END IF:NEXT k:IF p=5:PEN 10:PRINT AT 10,20;CHR$152:IF x=20 AND y=10
10FOR ry=1 TO 10:PRINT AT 10-ry,20;PEN 10;CHR$152;CHR$8;CHR$10;PEN 14;"*":POW:NEXT ry:EXIT IF 1:END IF:END IF:LOOP:RUN

I didn't fully understand the 120 line limit and the possible packing with SAM BASIC until the game was "finished" (and the above can actually be packed more e.g. PEN 14 can be entered as PEN14 for example). But the longest line is now line 10 with 119 chars.

The game is available on an disk image here.

If you're looking for a reference to SAM BASIC you can take a look at the original User Manual and the Complete Guide to SAM Basic by Graham Burtenshaw.

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 PyQt6 see my book, Create GUI Applications with Python & Qt6.

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 PyQt6 see my book, Create GUI Applications with Python & Qt6.

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 Snake in 10 lines of SAM Coupé BASIC — Simple Snake game in 10 lines of BASIC

2021-02-03T19:00:00+00:00

The Basic 10 Liner contest has been running for 11 years. This year (2021) the 10th competition, and the first time I've heard of it, thanks to Dean Belfield.

Since many BASIC dialects allow you to stack multiple statements onto the same line (SAM BASIC is no exception) there are additional category limits on characters per line, e.g.

Category "PUR-80": Program a game in 10 lines (max 80 characters per logical line, abbreviations are allowed).
Category "PUR-120": Program a game in 10 lines (max 120 characters per logical line, abbreviations are allowed)

I aimed for the PUR-80 category and got there with Snake.

This isn't a notable achievement, go see some of the great games from previous years like Sim City! But for a first attempt, I'm pretty chuffed.

Playing

You control the Snake with the keys Q, A, O & P for up, down, left, right. Eating food gains you a point and extends your Snake length by 1. If you chomp your own tail you die.

@chipper:l@ I mean, it's Snake, what do you expect?

You can download a MGT disk image containing 10 line Snake. To play, you can use the SimCoupe emulator. Insert disk image with File>Open. Load & Run with LOAD "snake80" LINE 1. Press ESC to break to source.

Readable code

The complete code is shown below with inline comments.

basic

# vars x, y: current coords
#      xs, ys: current x/y speed (always -1, 0 or 1)
#      l: length, starts at 1
#      fx, fy: x, y position of food
#      die: 1 if dead
LET x=10, y=10, xs=1, ys=0, l=1, fx=0, fy=0, die=0

# Pre-fill the tail memory with the starting location.
POKE &8000,x,y,x,y

# Setup the flashing effect for the food. Alternates color 11 between palette 50 (pink) & 127 (white).
# flashing every 5/50ths of a second.
PALETTE 11, 50, 127: POKE &5a08,5

DO
    # Move the head by current xs & ys.
    LET x=x+xs, y=y+ys

    # Wrap around on screen edges.
    IF x<0: LET x=31: ELSE IF x>31: LET x=0: END IF
    IF y<0: LET y=18: ELSE IF y>18: LET y=0: END IF

    # Draw the head. Only the head is drawn.
    PEN 12: PRINT AT PEEK &8000,  PEEK &8001;"█":

    # Blank out the square behind the tail.
    PRINT AT PEEK (&8000+l*2),  PEEK (&8000+l*2+1);" "

    # If our head is at the same position as the food, eat it. Update score.
    # ZAP is a built-in SAM BASIC sound effect. fx is set to zero when no food.
    IF x=fx AND y=fy: ZAP : LET l=l+1: LET fx=0: PEN 15: PRINT AT 0,0; l: END IF

    # Move the tail memory down 2 bytes, making way for the new head position.
    POKE &8002, MEM$ (&8000 TO &8000+l*2)

    # Poke current head location to the top of the tail memory.
    # Poked as 2 bytes, y then x (cols by rows, because we're printing).
    POKE &8000, y, x

    # Collision check (using pixels) the position in front of the snake. If we
    # see ourselves, we're dead.
    IF POINT (x*8+4, (19-y)*9)=12: LET die=1: END IF

    # If fx is zero (no food) add some randomly on the map and print it.
    IF fx=0: LET fx= RND (25)+3: LET fy= RND (10)+4: PEN 11: PRINT AT fy,fx;"▟": END IF

    # Scan the keyboard for input & update directions.
    LET i$= INKEY$ :
        IF i$="q": LET xs=0, ys=-1:
        ELSE IF i$="a": LET xs=0, ys=1
        ELSE IF i$="o": LET xs=-1, ys=0:
        ELSE IF i$="p": LET xs=1, ys=0:
    END IF

    # Exit when die=1.
LOOP UNTIL die

# POW is a built-in SAM BASIC sound effect.
POW

# Restart the game.
RUN

How it works

Each tick the head of the Snake moves 1 block in whichever direction it is going, by incrementing the x & y variables. We PRINT the head to the screen on each move. Since things remain where they are printed, we don't need to re-print the tail. But we do need to keep track of where it is both for collisions and to clear up after the tail.

To do this we POKE our current x & y positions into memory using one byte for each for simplicity sakes. On each tick we shift 2 x length bytes from &8000 to &8002 and poke the new y & x position into &8000 and &8001 respectively. By reading memory at &8000+2*l and &8000+2*l+1 we can get the last segment of our current length tail and delete it from the map by printing an empty space.

Tail is POKEd to memory, shifted right 2 bytes on each tick & the current x & y coords are POKEd to the head. The value shifted off the end is used to clear up after the tail.

Food is placed randomly on the map and we compare x & y positions of the food, to that of the Snakes head to register an "eat".

We're using two SAM-specific features here. First, is the use of the SAM palette flashing to flicker the food. By setting PALETTE 11, 30, 127 we color palette 11 (which we are using for our food PEN) to alternate between system color 30 & 27. The POKE &5a08, 5 sets the rate of alternating to every 5/50ths of a second to highlight the food. Second, is the use of the SAM BASIC built-in sound effects POW and ZAP which make pow and zap sounds, kind of. One negative is that doing this freezes execution of the BASIC program, so there is a small freeze when picking up food. But it's not too bad.

PUR 80

To squeeze the game down to fit the 80 character line limit needed the following tricks.

The &8000 address was stored in a variable o saving 4 chars each, or 2 for o+1, o+2.
Statements were folded back into lines using :, including breaking IF and ELSE blocks across lines. SAM BASIC doesn't care about line grouping.
Re-order statements to fit, e.g. PEN 12 is moved to the DO.. line.

I thought I'd need to drop the palette cycling effects at first, but by jiggling statements around it came in under. The final code is --

basic

1LET x=10,y=10,xs=1,ys=0,l=1,fx=0,fy=0,o=&8000,d=0:PALETTE 11,50,127
2POKE o,x,y,x,y:POKE &5a08,5:DO:LET x=x+xs,y=y+ys:PEN 12:IF x<0:LET x=31
3ELSE IF x>31:LET x=0:END IF:IF y<0:LET y=18:ELSE IF y>18:LET y=0:END IF
4PRINT AT PEEK o,PEEK (o+1);"ď":PRINT AT PEEK (o+l*2),PEEK (o+l*2+1);" "
5IF x=fx AND y=fy:ZAP:LET l=l+1:LET fx=0:PEN 15:PRINT AT 0,0; l:END IF
6POKE o+2,MEM$(o TO o+l*2):POKE o,y,x:IF POINT(x*8+4,(19-y)*9)=12:LET d=1
7END IF:IF fx=0:LET fx=RND(25)+3:LET fy=RND(10)+4:PEN 11
8PRINT AT fy,fx;"č":END IF:LET i$=INKEY$:IF i$="q":LET xs=0,ys=-1
9ELSE IF i$="a":LET xs=0,ys=1:ELSE IF i$="o":LET xs=-1,ys=0:ELSE IF i$="p"
10LET xs=1,ys=0:END IF:LOOP UNTIL d:POW:RUN

I wasn't originally packing the BASIC as compact as it can go, and this still isn't as small as it can go: you can even do FOR a=1to10 for example. As a result the longest line is line 9, with 74 chars.

The game is available on an disk image here.

Bugs

When placing food there is no check to make sure it's not going placed in the tail. Since we only draw the food when first placed, this means it disappears once the tail moves over (the end-tail blanking removes it). You have to try and remember where it is.

If you're looking for a reference to SAM BASIC you can take a look at the original User Manual and the Complete Guide to SAM Basic by Graham Burtenshaw.

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. ↩

Preserving the FRED disk magazine's text by decoding the Entropy Reader — Writing a SAM Coupé Reader parser in Python

2021-01-22T14:00:00+00:00

FRED was the most popular disk magazine for the SAM Coupé 8 bit home computer.Published by Colin MacDonald out of sunny Monifieth, Scotland, the magazine ran from it's first issue in 1990 through to it's last (82) in 1998.

For the SAM networking project I was hoping there might be some information on how the network worked in one of the issues -- maybe someone had done the groundwork for me. Disk images for all issues are available on World of Sam and can be loaded up in the emulator. But that made it hard to find anything specific -- you'd have to load up each disk, page through the magazine hoping not to nod off before you found what you're looking for. It would be easier if I could say search for "network" and find the issues where it was mentioned.

So I set about extracting the text files from the magazine -- which in this case meant re-implementing the decoder. If you find that kind of thing interesting, read on!

The extracted magazine text files (with addresses, etc. redacted) are now available on World of Sam!

FRED magazine

Each issue of FRED (from 4 onwards) had at least 2 text slots on the disk -- the editorial and the letters/reviews. These were viewable within readers on the disk, reachable from the main menu in slots A & B.

FRED 28 Main Menu Christmas '92 - the first issue of FRED I got with my Sam

Early issues of the magazine are in plain text (SAM Coupé ASCII) stored as simple data files with all pages in consecutive order. The following snippet is from FRED 16 the last issue with the Axe plain text reader.

text

                          Freditorial

  Greetings one and all from bonny Scotland (Och Aye The noo!)
  A free FRED to the first person who can tell me what it
means!!  Coming  up  to  Xmas  you'd expect loadsa new SAM games
wouldn't  you.  Unfortunately, the only one I think MIGHT be out
in  time  for  Xmas is Prince Of Persia! Although I did say last
month  that  it  had  been  released it seems there was a slight
miscalculation at Revelation (mmmm..that makes a change).

Each line is wrapped at 64 characters, with line-ends padded out to the full 64 characters. Blank lines are not empty and contain 64 space characters, including when they're at the end of the page. This is obviously pretty wasteful for memory/disk space, but has the advantage that each page takes up precisely the same amount of space, making paging forwards and backwards very easy. Displaying the text on the screen is simply a case of starting reading at page * page_size and dumping the correct amount of chars to screen.

Each page of text is 21 lines long, leaving a bit of space for controls (the heading is part of the text). That means each page is 21 * 64 = 1344 bytes long. A magazine 20 pages long would take 26,880 bytes or 26.25 KB. As the magazine grew, particularly the letters & reviews pages, this would take up an increasing % of the limited disk space (780 KB per issue), leaving less space for software. The solution was the new compressing Entropy Reader by Simon Cooke.

Entropy Reader

The Entropy Reader was used on FRED issues 17 (1992) onwards, right up to the final issue -- although it was tweaked a few times in between. Magazine text was compressed down to data files on disk by a compressor and then decompressed back to memory by the reader.

Starting this project I had no idea of the compression scheme. There are two simply ways to compress data -- tokenization and run-length encoding. The first uses a substitution table, where you can replace a entire word, or parts of words, with a control code. This relies on either calculating or knowing the most common words in the text. The second substitutes runs of identical characters with another. This isn't usually very effective in text because the occurrence of repeated letters is pretty low¹.

FRED 17 Magazine the first issue with the Entropy Reader

The magazine is stored in .mag files, separate from the reader program. There reader program was included on disk and didn't change between issues, although there were 3 variants through the lifetime of FRED magazine. Opening the data files in a hex editor gives the following garbled plaintext.

text

FRED manÂšmĂ.t accept noÂ.PontardawĂšÂ.ĂsponsibilfĂĂinjuriesÂ.Swans
Ă˛ÂincuĂśĂ˘ tryÂ° ĂĂÂśnoĂcĂšÂWalesÂ.Ăis line.ĂÂUAnybodĂşĂmemĂ
r a lÂ¸ablĂšlĂľtlĂšgamĂšon Âold SĂŞccĂşcallĂ˘BouldĂdaĂĂ If soĂyouÂ§suĂĂ
 Ă plĂ˛sĂ˘ Ă hĂ˛r ĂĂˇ a SAMgamesimilarĂĂĂĂis tyĂŞ is jĂ t about Ăady
ĂÂŽÂmomĂ.t ĂľgoesĂbĂş ÂnamĂšof "Wop Gamma"ĂĂis is jĂt a wĂkÂ° tĂľle,a
ĂŻaĂntĂ

In amongst the nonsense control codes there are clearly readable parts of words. The name of a game "Wop Gamma" is readable in it's entirety, as is the country "Wales", but the city Swansea appears as SwansĂ˛Â and consists of the following bytes.

s w a n s (242) (128) (22)

Skipping through the file we can see other similar substitutions e.g.

Simon Cooke -> S i m o n C (227) k e subscribers -> s u b s c r i (217) r s I've finally started getting -> I'v (249) f i n a l (209) s t a r t (226) g e t t (176)

From this we can start building a substitution table

Dec	Hex	Substitution
176	B0	ing
177	B1	een
195	C3	er
208	D0	ly
209	D1	th
217	D9	be
221	DD	re\s
222	DE	en
226	E2	ed
227	E3	oo
241	F1	d\sd
249	F8	e\s
251	FB	ic

It doesn't look like there is any particular pattern here, but maybe something will come out.

The reader program

We could carry on like this manually, building the table. But there are two problems -- (1) it's boring, (2) if the substitutions vary between issues, we'll have to do that again.

Thankfully, we don't need to do that. The FRED disks contain the reader program DOCREADER. As well as providing the reader interface, this program is responsible for decompressing the data back to plain text in memory -- meaning the code must contain the substitution table somewhere.

Opening the DOCREADER program in a hex editor, we can see a block that looks interesting.

text

addressÂscreensÂscreenÂ issueÂmemoryÂscreenÂ don
'tÂ SAMCOÂ SAMCoÂCoupeÂ FREDÂbytesÂ dataÂ it'sÂ fromÂ SAMÂ 19ÂšcodeÂ
CodeÂDataÂouldÂ outÂ hadÂCoupĂĽSAMCĂSAMCĂŻTheÂtheÂtioĂŽ atÂempĂ´19Âšc
omĂ°ComĂ°conĂłConĂł.Â yoĂľ'llÂereÂYouÂ itÂ.)Ân'Ă´itĂšAtÂ19ÂšinĂ§eeĂŽanĂ
¤AnĂ¤ghĂ´maĂ§prĂŻouĂovĂĽagĂĽ -Â'mÂ'sÂYoĂľ IÂanĂ´iaĂŹ  Â Â¨eĂ˛,Â Â.Â!Â?Â
AÂoĂ˛sĂłeĂĽcĂ¨sĂ¨uĂŽlĂštĂ¨TĂ¨TĂŻtĂŻoĂˇqĂľQĂľBĂĽbĂĽUĂ°uĂ°RĂĽrĂĽeĂŽEĂŽuĂłU
ĂłeĂ¤o ĂŻ.Â˘!Â˘?Â˘;Â:Â)ÂpĂĽPĂĽiĂ˛IĂ˛mĂšpĂ°IÂdĂ¤eĂĄfĂŚsĂłiĂ´rĂ˛aĂ´AĂ´eÂ
yÂiĂŁ

The most obvious block is beginning with the word address (3rd line). This consists of a series of words delimited with hex A0 (dec 160)². But this isn't the same partial substitutions we found earlier. If these worked in the same way, we would be able to find them in the reader code -- for example, the longest partial string we found ing. But it isn't there (neither is ly, except in plaintext help message at the end). So, something is going on here.

At the beginning of the block we see a series of single letters and numbers (but not all the letters and numbers) arranged, separated by hex 01 (dec 1). Notice that the list includes all vowels -- my first thought was that this is a list of the most common letters in English, though why we'd be substituting single characters is a mystery.

Converting

Despite the unanswered questions, we have enough information to get started on our converter. First, we can get whole-word substitution map from the DOCREADER with the following code (byte offsets hardcoded for now):

python

with open('DOCREADER', 'rb') as f:
    data = f.read()

#Âdata is bytestring, isolate substitutions (byte 918 onwards)
data = data[918:918+222]
subs = data.split(b'\xa0')
print(subs)

Which produces the following output.

python

[b'address', b'screens', b'screen', b' issue', b'memory', b'screen', b" don't", b' SAMCO', b' SAMCo', b'Coupe', b' FRED', b'bytes', b' data', b" it's", b' from', b' SAM', b'\x7f 19\xb9code', b'Code', b'Data', b'ould', b' out', b' had', b'Coup\xe5SAMC\xcfSAMC\xefThe', b'the', b'tio\xee at', b'emp\xf4\x7f19\xb9com\xf0Com\xf0con\xf3Con\xf3.', b" yo\xf5'll", b'ere', b'You', b' it', b'.)']

We don't know the substitution codes for these yet, but we can compare the output of DOCREADER with the input mag file to work them out. Loading up FRED 28 we don't need to look far to find a match -- issue is in the first line.

FRED 28 Magazine with the reader showing the first page.

The text reads:

...And what better way to start an issue than with a compliment, heh heh. Ah yes, the Christmas issue.

The word issue is in our substitution table, and appears twice on the first page. Here is the data from the mag file.

text

FREDĂĂĂˇÂźYOU ĂĂˇ is!!!ĂÂP.Âł whĂˇ ĂttĂ waĂşĂ start anÂĂan wĂľh
a ÂĄlimĂ.t,hehĂhehĂ AhĂyesĂÂChristmas iĂueĂ

The first issue is substituted with 84 (dec 132) , start anÂĂan (it must be the first character after the first 'an'). The second isn't substituted, but instead has it's double-s substituted with CB (dec 203). This suggests the word substitution only works on isolated 'whole words' surrounded by space -- the second issue is followed by a full-stop and a space, which has been substituted by C6 (dec 198). That gives us a few more manual entries for the substitution table.

Dec	Hex	Substitution
188	BC	's\s
203	CB	ss
198	C6	.\s

I would expect the word substitution table to be stored ordered in the reader file (so the next word uses a code 1 greater than the previous). To check this we can assign the codes in order and then compare another of the substituted words that appears multiple times -- for example the which is replaced with 9C (dec 156).

The following will assign the codes in order from 129 up to however many items there are in subs.

python

dec = range(129, 300)  # too long, will truncate
word_map = dict(zip(dec, subs))
print(word_map)

Which gives the following output...

python

{129: b'address', 130: b'screens', 131: b'screen', 132: b' issue', 133: b'memory', 134: b'screen', 135: b" don't", 136: b' SAMCO', 137: b' SAMCo', 138: b'Coupe', 139: b' FRED', 140: b'bytes', 141: b' data', 142: b" it's", 143: b' from', 144: b' SAM', 145: b'\x7f 19\xb9code', 146: b'Code', 147: b'Data', 148: b'ould', 149: b' out', 150: b' had', 151: b'Coup\xe5SAMC\xcfSAMC\xefThe', 152: b'the', 153: b'tio\xee at', 154: b'emp\xf4\x7f19\xb9com\xf0Com\xf0con\xf3Con\xf3.', 155: b" yo\xf5'll", 156: b'ere', 157: b'You', 158: b' it', 159: b'.)'}

With issue lined up at 132, that gives 152 for 'the', rather than the 156 we wanted. Bugger.

But there are a few weird entries in there, containing something other than plain text -- other codes > 127 ASCII in the table, e.g. Coup\xe5SAMC\xcfSAMC\xefThe, and what's yo\xf5'll? There is some additional structure to this lookup table that I'm missing so far. Pressing on I identified a few more manual entries.

Dec	Hex	Substitution
176	B0	ing
177	B1	een
178	B2	and
179	B3	And
180	B4	ght
181	B5	mag
182	B6	pro
	C5	double space

As substitutions are added it becomes progressively easier to map the remaining letter groups. For example

N\xf7ural Disasters - Earth\xd6ake and Typhoon\xba for

It's obvious that 0xD6 is "qu" and 0xF7 is "at". After a few more manual assignments to the table we're getting there, and the text is almost readable.

Stevie T forgotten to write it? Has he been kidnapped by a gangof rebellious tin-openers? Or is our postal system simplyfalling to pieces? Who knows? \xd3 make up for this utter tragedy,we\'ve decided to rewardyou all for being such loyal readers by(a) being \xcfnecessarily corny and ingratiating and (b) by givingyou part 2 of "Rachel! Now, canyou honestly say we\'re not goodtoyou? (Andyou\'d better be thinking "Gosh, how jolly generous"otherwise we will NOT be pleased).

In some places the words are run together. Some of these e.g. BrianMcConnell are due to the word-wrapping on the SAM Mode 3 screen -- no space is inserted at the end of a line. But in others e.g. goodtoyou it's a problem -- the "to" might probably be "to " to "you" to " you". There is no way to check these bar comparing with the output of the reader line by line, and this is getting a bit tedious.

At this point I thought I'd go looking for the source code for the compressor/reader, but landed on something far more helpful -- documentation³. It's even rather good.

The compressor

Below is a snippet from the documentation.

Document text in a MAG file is compressed using a combination of run-length compression and tokenised strings. Each page is 1344 bytes long (64 characters per line, 21 lines per page). Data bytes below 128 are passed directly to the output routine, bytes with the value 128 are passed onto the run-length subroutine, and the rest (129-255) are passed onto the detokenisation routine. Arguably, better compression could be provided by allowing tokens to also have the value 0-31 -- increasing the total number of tokens available from 127 to 159 -- but as this is not done by the Document Reader, and there are no further incarnations of the original reader program planned, this is a moot point.

So, the compressor actually uses both tokenisation and run-length compression, but the run-length applies only to spaces in the text. That explains why it wasn't more noticeable in the generated output.

The compressor works by looking for a string of 3 or more spaces in the document text. so this can lead to considerable savings). Thus, whenever a code of &80 hex is found in the compressed text, the next byte is taken, and this is used as a counter to print spaces to the screen. Occurences of two consecutive spaces are compressed by the tokenising routine.

This last point makes sense because run-length encoding would compress a 2-space block to 2 bytes, a waste of time [space-marker][2], while replacing 2 spaces with a 1 byte token nets a (small) saving.

The run-length encoding is simple to implement in Python, the code below gives an example. We read a byte at a time, if the the byte has a value of 128 (80 hex) it's a space marker. We read the next byte and add that many spaces to the output, skipping ahead an extra byte.

python

result = b''
i = 0
while i < len(data):
    byte = data[i]

    if byte == 128:
        # Run length compression, get another byte.
        i += 1
        length = data[i]
        result += b' ' * length
    else:
        char = sub_map.get(
            byte,
            bytes([byte])
        ) #Âsubstitute if exists, fallback to existing.
        result += char #.decode('utf8')

    i += 1

print(result)

The addition of the run-length decompression makes the text look a lot more like it should, here wrapped at 64 characters.

text

In  eremeantime though, Merry Christmas, and\xbehopeyou all getn
ice FRED software articles inyour stockings\xc7





BM                          Credits

Editor:- Brian McConnell
Publisher:- FREDPublishing
                                                               T
hanks this month to:-

                Charles Hawes\xc1\xd8n Wyatt
                   Calvin Allett\xc1Banzai\xc7
                              Mork\xc7  Hipposoft
                          Simon Cooke   BTB
                         Steve Taylor\xc1Ian Slavin
                             Andy Monk\xc1Electron Aff in\xad


           REMEMBER:-\xc1 yo\xf5\'llexpression "kill 2 birds wit
h one stone" is notmeant  to be taken literally. It is, however,
 quite easy, ifyoucatch them in a large net first\xa5

The eremeantime looks a mis-tokenisation by me and there are others. The documentation actually contains a copy of the entire substitution table(!) but it would still be nice to be able to extract this directly from the MAG file -- it'll allow us to decompress magazines without knowing which version of the reader they are using.

Thankfully the documentation gives a hint where I was going wrong.

If a token is found, 129 is added to the token's dictionary reference number, and it takes the place of the equivalent text in the compressed data. Thus all it's necessary to do to decompress the tokens, is to have a copy of the appropriate dictionary, and then to use the token data to access that table.

...and...

Each token has bit 7 set on the last character, to mark that the end of the token has been reached.

This explains what's going on with the substitution table and why we couldn't just split it using 0xA0. The last character of each entry in the table has it's high (127) bit set. The value 0xA0 is actually a space 0x20 (dec 32) with it's high bit set (0x80 + 0x20 = 0xA0) Some of the tokens end with a space, others do not!

With that crucial bit of information we can now parse the token table out of the reader file. We can start iterating from the some position (here 129, which I think is the beginning of the table) and look for the high bit of a byte to be set, using byte & 0x80.

python

data = data[918:918+408]
tokenix = 129 # tokens start at 129.
tokens = {}
token = b''
i = 0
while i < len(data):

    byte = data[i]

    if byte & 0x80:
        # High bit set, subtract, store, and get ready for next token.
        byte -= 0x80
        token += bytes([byte])
        tokens[tokenix] = token
        tokenix += 1
        token = b''
    else:
        token += bytes([byte])

    i += 1

print(tokens)

This generates the following complete token table, with "the" assigned the expected value of 156.

python

{129: b'address ', 130: b'screens ', 131: b'screen ', 132: b' issue ', 133: b'memory ', 134: b'screen ', 135: b" don't ", 136: b' SAMCO ', 137: b' SAMCo ', 138: b'Coupe ', 139: b' FRED ', 140: b'bytes ', 141: b' data ', 142: b" it's ", 143: b' from ', 144: b' SAM ', 145: b'\x7f 199', 146: b'code ', 147: b'Code ', 148: b'Data ', 149: b'ould ', 150: b' out ', 151: b' had ', 152: b'Coupe', 153: b'SAMCO', 154: b'SAMCo', 155: b'The ', 156: b'the ', 157: b'tion', 158: b' at ', 159: b'empt', 160: b'\x7f199', 161: b'comp', 162: b'Comp', 163: b'cons', 164: b'Cons', 165: b'. ', 166: b' you', 167: b"'ll ", 168: b'ere ', 169: b'You ', 170: b' it ', 171: b'.) ', 172: b"n't", 173: b'ity', 174: b'At ', 175: b'199', 176: b'ing', 177: b'een', 178: b'and', 179: b'And', 180: b'ght', 181: b'mag', 182: b'pro', 183: b'oum', 184: b'ove', 185: b'age', 186: b' - ', 187: b"'m ", 188: b"'s ", 189: b'You', 190: b' I ', 191: b'ant', 192: b'ial', 193: b'   ', 194: b' (', 195: b'er', 196: b', ', 197: b'  ', 198: b'. ', 199: b'! ', 200: b'? ', 201: b'A ', 202: b'or', 203: b'ss', 204: b'ee', 205: b'ch', 206: b'sh', 207: b'un', 208: b'ly', 209: b'th', 210: b'Th', 211: b'To', 212: b'to', 213: b'ow', 214: b'qu', 215: b'Qu', 216: b'Be', 217: b'be', 218: b'Up', 219: b'up', 220: b'Re', 221: b're', 222: b'en', 223: b'En', 224: b'us', 225: b'Us', 226: b'ed', 227: b'oo', 228: b'."', 229: b'!"', 230: b'?"', 231: b'; ', 232: b': ', 233: b') ', 234: b'pe', 235: b'Pe', 236: b'ir', 237: b'Ir', 238: b'my', 239: b'pp', 240: b'I ', 241: b'dd', 242: b'ea', 243: b'ff', 244: b'ss', 245: b'it', 246: b'rr', 247: b'at', 248: b'At', 249: b'e ', 250: b'y ', 251: b'ic'}

Running this substitution table and the run-length encoding against the compressed text, produces the following perfectly decompressed output.

Colin "Fuhrer" Macdonald here has just ordered me to point outthat you, the reader, should always make cheques payable to FREDPublishing. Some people, you see, have been practising what canonly be called "creative cheque writing", and have been makingthem out to all sorts of strange companies like FRED SoftwareLtd., and Belgian Massage Inc., (okay, so the last one was ajoke. As far as I know, anyway).

Page wrap

Each page is 1344 bytes long (64 characters per line, 21 lines per page). So far we've been ignoring line breaks but to get completely readable text we need to add them in.

Splitting lines is simply a case of iterating through the data, in 64 byte chunks, but first we need to be sure we have the correct start position in the data file. For v1.1 and v1.2 the files have a short header which contains the offset at which the data starts. The following will extract and calculate this offset for us (based on the documentation).

python

offset = int.from_bytes(data[0:2], byteorder='little') - 38233

Using this as our start position we can now iterate forwards in 64 byte blocks to get well-formatted output.

text

b'BM                            News                              '
b'                                                                '
b"The  biggest  piece of news this month is that you don't have to"
b"put  up  with a knackered SAM anymore!! (Although, if your SAM's"
b"knackered I don't know how you're supposed to read this and find"
b'out.  Hmmm).  Yes,  those  two faithful SAM people Adrian Parker'
b'(from MGT, Blue Alpha, and SAMCo) and Mark Hall (from MGT, SAMCo'
b'and  SAMTech)  have  joined  together and resurrected Blue Alpha'
b'Electronics!  Already  in  operation, this "new" company can now'
b"repair all those little problems you've been bothered by. Prices"
b'for repairs are:-                                               '
b'                                                                '
b'SAM (not including disk drive) - `30                            '
b'Interfaces                     - `18                            '
b'Disk Drive                     - `18                            '

The text above shows all the remaining trailing spaces in place, but we could also truncate the lines.

We also need to insert blank lines at the end of every page for readability -- since the original reader displayed the text page by page, it is possible for there to be text at the very bottom of one page that would run against the header on the following page. It's not a disaster, but it's ugly. To solve this we can just count every 21 lines and insert a blank (empty) line into the output.

Finally, can now convert our text to strings and make some simple substitutions to account for the differences between the SAM Coupé ASCII table and UTF-8.

python

.replace('\x5E', '↑') # is ^ by default,
.replace('\x5F', '_')
.replace('\x60', '£')
.replace('\x7F', '©')

The output is now ready to be written to text files.

Different versions

If all the versions of the reader were the same, this would be the end of the matter. But there are actually 3 different versions used on FRED magazine. The different versions all use different subsitution tables, store them in slightly different locations in the file, and change the format of the mag file header.

To handle these cases two alternatives were added to the converter --

if the original reader executable is available, this can be passed to the converter and will be used as the source for the dictionary. This table is located in different places in the different versions, so a series of long probably-unique bytes are used to find the table -- there are limited versions out there, so this is fine
the known dictionaries are included in the converter, and can be specified from the command line

Final steps

With these modifications it was possible to convert all the FRED magazine text (and letters, and other content) to plaintext, with the following steps --

the FRED magazine DSK files were downloaded
the magazine text and reader files were extracted from the the disk images using samfile then copied to a series of folders
the files were processed to plain text, passing in the reader file for the specific magazine

The screader converter tool has been released as a Python package. You can install it with

bash

pip3 install screader

Run the tool with screader -h to get the command line help.

text

screader -h
usage: screader [-h] [--reader READER] [--readerversion {0,1,2}] [--skipinstructions] [--format {text,markdown}] [--outfile OUTFILE]
                mag [mag ...]

Extract Sam Coupe Entropy Reader files.

positional arguments:
  mag                   source MAG file(s) to process.

optional arguments:
  -h, --help            show this help message and exit
  --reader READER, -r READER
                        Path to the reader executable (token table will be extracted).
  --readerversion {0,1,2}, -rv {0,1,2}
                        Version of compressor token table to use (0, 1, 2 for v1.0, v1.1, v1.2 respectively).
  --skipinstructions, -s
                        Skip first page (instructions)
  --format {text,markdown}, -f {text,markdown}
                        Output format, one of (text, markdown).
  --outfile OUTFILE, -o OUTFILE
                        Output file (filename will be used for format, if not specified with -f. Output to <infile>.txt if not provided.)

You can see the full source code on Github.

Uploading

Once all the files were converted to plaintext, the content was uploading onto World of Sam, the home of all things SAM Coupé. For an example see FRED28 --- scroll down for the magazine text. You can find all issues of FRED here.

Each magazine was manually redacted to remove personal info such as addresses, email addresses (later) and phone numbers. This was by far the most time-consuming part of the process, as it wasn't fully automatable. I just read the lot and built a table of regex searches for things that look like addresses, in case I'd nodded off the first time. Hopefully I got them all.

I still haven't got to the issues < 17 -- which are arguably simpler, since they're just in plain text. Something for a rainy day.

...and the Network?

No, I didn't find anything about the network, beyond what was already on World of Sam.

Oh well.

Or is it? ↩
160 is 32 + 128... Wait for it. ↩
I'd searched for this before, but probably thought it was called "FRED reader". ↩

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!

Network Interface Design — Details of the SAM Coupé networking circuitry

2020-10-23T09:00:00+00:00

In the first part we looked at the information about the SAM Coupe network available in the user manual, technical manual and other examples of networking systems that may have influenced the design on the SAM Coupe. Next I'm going to look at the electrical design of the SAM Coupe and the other devices, to see if they really are compatible and whether we can knock together an interface to start reading the wire protocol.

We may as well start with the only peripheral I know of that plugs into the SAM coupe Network ports: the Messenger.

Messenger

The Messenger was an MGT device which allows snapshots of software running on a ZX Spectrum to be downloaded (via the network port) to the Sam Coupe to be run there.

The full schematic by Miguel Angel Rodríguez Jódar is available on zxprojects.com. The particular bit we're interested in (optocoupler/network port) is copied below.

This shows pins 4 & 5 being fed into an optocoupler (serial in) and serial out coming via pin 3 & 1 (with pin 1 pulled high, not grounded). So, data from the Sam to the Messenger appears to be coming via the MIDI pins, not the network. While data from the Messenger to the Sam does use the network pins. Odd.

IDEA: This might be necessary on the Messenger because it only has a single cable, plugging into the outermost network port on the Sam.

DISCiPLE +D

As we've already looked at in the previous part, the DISCiPLE was an MGT device for the ZX Spectrum which added an easier to use disk drive and IF1-compatible networking.

The schematic (found on spdns.de) shows how the IF1 network was wired. Below is a crop from the bottom-right of the full schematic, showing the microphone-socket inputs. By default the ports are grounded, but inserting a plug latches that open, allowing the data to be read. This matches up with what we read in the ZX Interface 1 handbook – machines shouldn't be connected in a loop, as the empty sockets at each end terminate the network.

Note that receive/transmit is on the same wire – there is only one wire. Both network plugs are wired together (giving pass through) and transmission pulls this line high (+5V).

Since the Sam Coupe sockets (DIN plugs) don't have physical latches, there would need some other mechanism to terminate the network (if it's not a loop).

IDEA: I'm wondering now if cable (with the paired wires on one side) acts to un-terminate the network somehow.

Sam Coupe

The full schematic (corrected) of the Sam Coupe is available from VELESOFT. The network (MIDI) part is shown below. This is a bit confusing as the pins are shown in order (1-7) rather than socket order.

The output is driven by the line on the far left MIDOUT and input is returned to the system via the line in the top right MIDIIN. The labelling on the sockets shows that many of the pins (e.g. NET+ or MI+) are simply wired through/identical on the two sockets.

I've confirmed these connections using a multimeter.

Putting the pin labels into a table with the original socket information (left from the User Manual/right schematic) we get the following listing.

Pin	Network IN	Network OUT
1	NET- / MN-****	NET- / MN-
2	nc	0V
3	NET + / MI+	NET+ / MI+
4	MI+	MO+
5	MI-	MO-
6	NET - / 0V	NET- / 0V
7	NET+ / NET+	NET+ / NET+

On the MIDI diagram in the User manual the let hand image was labelled MIDI OUT but there was no equivalent label on the network. Looking at the schematic we can see that MIDI and the network function identically (same circuit) just with the addition of resistors on the network side. So are the ports network IN and OUT? Not really, the wiring is identical for both ports, meaning you can use either to connect the SAM.

Note that this diagram doesn't show the correct socket numbering (it's backwards), do not wire your cable like this.

So, if direction is irrelevant, what is the effect of wiring together pins 6&1 and 3&7 on the network cable? An annotated version of the schematic is shown below, with NET- lines highlighted in blue (ground) and NET+ lines highlighted in red (+5V). The signal input and output are shown by the grey arrow line.

As mentioned, NET- and NET+ (pins 6&7) are wired through from one socket to another, and NET+ is driven by the computer (via MIDOUT). So, pins 6&7 are sufficient to transmit data and share it with all computers on the network, but each computer needs pins 1&3 connected (to 6&7 respectively) to be able to read the incoming data.

This makes the SamCo Messenger even weirder, since it's possible to communicate using just one network port, and MIDI & network are electrically connected why use both pins? Maybe to save a resistor in the device.

Looking at the highlighted part of the schematic, we can see that the NET+ line is pulled high by default, and pulled low (to GND) for each bit. The base of transistor N2 is connected through a resistor, to 5V, pulling it high and conducting 5V to NET+. Signal to the base of N1 opens the transistor, connecting the base of N2 to GND, switching it off.

High-off, low-data is in common with standard UART data transmission, and also the standard for MIDI communication. Is the SAM network just a MIDI network?

@chipper:l@ TL;DR yes.

Network topology

Since the sockets are wired through, pins 1&3 can be connected on either socket. However, every SAM in the network needs to have those pins connected on at least one socket in order to read the data. The options for network topology are –

loop of machines, using the cable with pins 1->6 & 3->7 wired together, each Sam getting one magic end of the cable each
linear network, with a terminator plug on the end (one end only) which makes this connection (a dangling cable would also work)

Since I've never heard of plug terminators for the Sam Coupe, or a dangling network cable, it seems like the loop was the intended setup.

There is enough information here now to rig up a serial device and see what we can see on the net.

Based on what we've found, the SAM network looks to be using the built in MIDI support, at least electrically. The MIDI standard uses a UART connection at 31.25 Kbaud, so that would be a good place to start.

Turns out on the Atari ST it was also possible to use the MIDI network for basic networking.

In the previous part we discovered that the network data is sent on pins 6&7, and read from pins 1&3. The data is transmitted line-high, that is 5V is off and 0V is on, in keeping with UART standard. The ZX Interface 1 Wikipedia article gives us a speed of 100 kbit/s for the network, which seemed a good place to start. The Sam Coupe Technical manual lists 31.25 kbit/s for MIDI, but it's not clear if this also applies to the network (it does).

Flashing a LED, or how I found out the port numbering is backwards

To test that we can read data out of the network port I hooked up a simple circuit to the output pins on the network socket. From the schematics we know that a signal on the MIDI out pin drives our output pin high, to 5V. To see this in action we can connect a LED and resistor across this pin to ground.

It was at this point that I discovered that the diagram in the main body of the user manual has the pin order precisely backwards. The correct order is shown in the appendix.

With that fixed, we can trigger output to the network by setting the current device number of the machine with device n1 ¹ and then saving the current (empty) BASIC program with save "test". As you can see below, this creates two flashes on the LED.

@chipper;l Why two? We'll find out in a minute.

Moving this circuit to the other port confirmed that the MIDI in and MIDI out ports are electrically connected on the network pins. Our little dongle works just the same connected to either port -- since network out is available on the in port, we should be able to do full 2-way communication with a single port. We'll find out later if it matters which for the input.

Line specification

@chipper:l@ TL;DR it does.

Next we'll look at sending data to and from the SAM coupe from the Raspberry Pi.

actual network number is irrelevant as we'll discover later, this just enables network mode ↩

SAM Coupé Network — Figuring out the SAM Coupé 8 bit home computer's networking abilities

2020-09-23T07:00:00+00:00

The SAM Coupé was a British 8 bit home computer that was pitched as a successor to the ZX Spectrum, alongside improved graphics and sound and higher processor speed it also had in built support for MIDI and networking. The manual talked up how the SAM was ready to expand and the accompanying image captured my imagination, thinking of all the possibilities this little box had in it.

This diagram seems to suggest the network is a ring network.

25 years later and my Sam Coupe is still yet to connect to a network (or scanner/digitiser, VCR, modem, light pen...) and I thought it was time to do something about that.

There is now an Ethernet networking option available for the Sam Coupe – the Trinity Ethernet Interface from Quazar. If you want to get your Sam Coupe online that's probably a far more sensible option – this is about getting the original hardware to do what it was intended.

User Manual

The Sam Coupe User Manual mentions the networking capabilities, under a section titled "Edication" (p118) about using the Sam Coupe in an educational network setting.

This setup is a bit different to how we think of networks now, with a single host #0 (teacher) being the controller of the network, broadcasting data to the others to LOAD. Oddly, after starting talking about networks, over the page (p119) it then starts talking about streams – a related, but separate thing, which allow you to direct output to devices. Maybe this allows you to send data to network stations by doing something like OPEN #6; "n5" (it doesn't ¹)

In the list of BASIC commands (p140) there is a mention of using DEVICE n<number> to select which network device (computer) to communicate with (LOAD from or SAVE to).

python

DEVICE N5 use Network Station 5

The glossary (p153) there is this helpful note –

Network Up to 16 Sam Coupés can be linked in a network, with Channel 0 as the broadcast station and Channels 1 - 15 as personal operator stations.

This gives us a maximum size of the network (16 machines) and that individual machines have their own channel number. But we're none the wiser in how to actually wire multiple machines together – is the network is intended to be set up as a loop (as in the first diagram above) or linear. How are network station numbers assigned?

Finally, the appendix (p171) has a wiring diagram for creating a network cable. Note that MIDI is on the same port, but using different pins.

@chipper:l@ Don't wire your cable like this, kids. I find out later it's upside down.

This is interesting, since it shows that pins 6 & 1 NET- should be joined together, and to the screen – suggesting that these are ground pins. The pins 3 & 7 are also joined together and provide the signal. What isn't clear is what is meant by "FROM NETWORK PLUG" since both sides of this cable are going to be plugged into a Sam (whether in a loop or linear topology).

That's basically it for the User Manual, next up the technical manual.

Technical Manual

Unfortunately, there's even less information about the network in the technical manual than in the user manual, with the only useful thing being a pin diagram for the two network ports (shared with MIDI in and out) matching what is in the user manual. The section about MIDI gives the maximum data rate as 31.25Kbaud (MIDI standard) although it's not clear if this also applies to the network – everything else here is about MIDI. There is no information here about voltages, transmission/network protocols, or how to wire the SAMs together.

Networking Article by Malcolm Perry, FRED40

In FRED issue 40 there is a article about Sam Coupe networking by Malcolm Perry. The full text is worth a read – I'll copy the key parts here.

Firstly the connecting lead. The handbook (p171) shows a lead that has pins 1&6, 3&7 joined at one end but only pins 6&7 used at the other. This single lead will give data transfer in one direction only.

A clue! P108 vaguely shows the SAMs connected in a closed loop, use a second lead and providing they're connected the right way round so that each SAM has an end that has the pins linked then two way transfer is possible.

This suggests that the machines must be connected in a loop for the network to function. If true that would mean that pin 7 is a passthrough in one direction only (there is no way for data to get back up the line).

Incidentally, the data leaves the SAM via pins 6&7 and receives via pins 1&3. I have not worked out the implications of the same SAM having data fed back into itself by the linking of pins 3&7.

Based on the wiring diagram I though pins 1&6 were just grounded, will need to check this on the machine itself. There seem to be problems with this setup when actually using software that was supposed to support the network, for example –

Unfortunately, a lot of programs seemed to lock up when both leads were connected. I found that many routines trigger the Network output and leave it high. It seems that if pin 3 is taken high then the keyboard is locked out, no doubt to prevent data corruption during network use. However, as pin 3 is connected to pin 7 then when the programs drive an output on network and leave it there things come to a halt and the computer is locked up.

The article has a reply from Colin Macdonald (FRED editor) describing using the network, and potential problems with only two SAMs in a closed loop.

When at SAMCo last Summer, Adrian, Charles and myself did some experimenting and besides having fun we did actually produce some interesting results!

Yes, there does seem to be a problem with two SAM's in a closed loop but we didn't investigate as far as Malcolm as done. We successfully "daisy-chained" four SAMs together with each one being a different station number.

So there is a problem with 2 computers in a loop. This might be a timing problem with data being received back to the originating station too quickly, while it's still broadcasting. Or maybe you don't want a loop at all? The phrase daisy-chained is a bit ambiguous here.

Looking for more info on networking was one of my motivations for extracting all the text from FRED issues, but this was all there was!

ZX Net

The last bit of the puzzle I could find online was on the The Computer Sam Coupe page by Aleš Keprt, which lists some basic technical specifications of the computer. Under Network, the Sam Coupe network is described as "Built-in ZX Network-based serial system, supported by DOS".

The ZX Network was a Sinclair ZX Spectrum networking system, available on the Interface 1. Miles Gordon Technology was founded by former employees of Sinclair Research (Alan Miles & Bruce Gordon) so it wouldn't be too far a stretch that the SAM Coupe networking system was based on this earlier system.

Looking at the ZX Microdrive and ZX Interface 1 Manual there are certainly some similarities, at least in capabilities.

ZX Spectrum Microdrive & Interface 1 Manual cover, you can almost smell the 80s

Chapter 5 has a mention of streams, which sound awfully familiar (p 21 & 22).

The network is covered in Chapter 7, and also sounds very similar to the networking capabilities in the Sam Coupe manual. On the first page (p29) we see the following diagram showing 3 ZX Spectrum computers connected in a line (not a loop!) together.

The accompanying text says

Using the lead supplied with each Interface you can link up as few as two and as many as sixty-four Spectrum computers, as shown below. Note, however, that you and your friends should not form a loop of computers: the computers at each end of the net should never be connected to each other. Each should be left with one net socket free.

So, this network can be up to 64 stations (I wonder if anyone ever managed that!).

DISCiPLE +D

The DISCiPLE +D was an improved disk interface for the ZX Spectrum developed by MGT, the same guys behind the SAM Coupe itself. The SAM disk operating system SAMDOS was also based on the DISCiPLE's GDOS: it seems likely at least some ideas for networking would have carried over. The DISCiPLE +D network is ZX NET (Interface compatible).

Looking at the DISCiPLE manual chapter on networking (section 9.1) it says the DISCiPLE is IF1 (ZX NET) compatible, using the standard 64 base stations.

GDOS (DISCiPLE) implements an IF1 compatible network, with some enhancements. Up to 63 Spectrums can be connected together and share their resources (files and printers) simply through a 3.5 mm mono jack cable. Each station is given an unique station number ranging from 1 to 63.

As on the SAM there are roles assigned to these stations, and #0 is broadcast -- although on the SAM the master station was expected to broadcast.

Number	Purpose
0	Broadcasting
1	Master station
2-9	Assistants (they load the system file)
10-63	Pupils or assistants (pupils do not load the system file)

The commands used in GDOS for loading and saving over the network are also familiar, although using d for stations (which is used for disks on the SAM) and devices for networking loading and saving are included with the filename on SAMDOS.

basic

LOAD d1;"pippo"           first load the file, a Basic program in this case
SAVE N16                  send it to station 16

The GDOS description also mentions being able to get a directory of another stations disk using:

basic

CAT d1

Which (as far as I know) isn't possible in SAMDOS.

Atari ST

I've also discovered -- thanks to this tweet by Peter Fletcher -- that the MIDI ports on the Atari ST were also sometimes used for networking, as in the game MIDI maze. That page mentions that Up to 16 computers can be networked in a "MIDI Ring" by daisy chaining MIDI ports that are built into the Atari ST series. ²

So far...

With everything we've read so far, we can be reasonably sure that --

the network has 16 stations, each with their own channel number
channel 0 is the broadcast station, 1-15 are the personal operator stations (it's not clear if channel 0 has to be dedicated station, or all operator stations can broadcast)
there are 2 network ports, and we have a wiring diagram

Superficially the description of the SAM network matches with the ZX Net, aside from the number of stations. But we still don't know if the ZX protocol is actually used, or how the network should be wired together.

Next I'm going to dig into the schematics of the Interface 1, DISCiPLE & Sam Coupe to see if we can settle how the networking works electronically. Once we have that we rig something up to start reading/writing the protocol on the wire.

The command is accepted, but it doesn't open a network stream. ↩
Makes me wonder if the MIDI-networking on the SAM was inspired by the ST? MIDI Maze was released in 1987. ↩

Create GUI Applications with Python & Qt5, 4th Edition now available (PyQt5 & PySide2) — The hands-on guide to make apps with Python

2020-06-25T12:06:00+00:00

Hello! This morning I released a new update to my PyQt5 book Create GUI Applications, with Python & Qt5. This is an enormous update, expanding it from 258 to 665 pages and adding 211 complete code examples.

To celebrate the milestone the book is available this week with 20% off. Readers get access to all future updates for free, so it's a great time to snap it up!

This is the 4th Edition of the book and adds a number of entirely new chapters including MVC-like model views, SQL database-views, plotting with matplotlib & PyQtGraph, custom widgets & bitmap graphics, concurrent programming with threads and processes and theming Qt applications.

Existing chapters have been expanded with more examples and step-by-step guides to using them. All source code shown in the book is available as standalone, runnable, examples to try out and experiment with.

Chapters have been updated and expanded with new examples and more detailed explanations and diagrams. Cross-platform screenshots show how your application will look on different systems. Starting from the basic principles of GUI development in Python and building up to more complex topics.

Learn how to use Qt's MVC-like model views architecture to sync data with widgets, including querying and editing SQL databases from within your applications.

Tired of the default application look? Use styles, palettes and Qt Style Sheets to completely customize the look and feel of your applications.

Discover how to create your own widgets to use in your Qt applications. Starting from the basics of bitmap graphics and building up to a fully-customizable widgets.

Use threads an processes to perform long-running calculations or communicate with remote services, without locking up your applications. Receive data back from threads and processes and display progress bars. Stop and pause running jobs from your UI.

Visualize data inside your applications, using matplotlib or PyQtGraph. Sync plots with external threads to create live updating dashboards to visualize data in real-time.

There is also a PySide2 edition of the book available, which features largely the same content, with examples converted to "Qt for Python". Purchasing either book gets you access to both editions, including any future updates of either.

Feedback, as always is very welcome!

Get the PyQt5 book Get the PySide2 book

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

LearnPyQt — One year in, and much more to come. — A quick retrospective on 2019

2019-12-31T00:12:00+00:00

It's been a very good year.

Back in May I was looking through my collection of PyQt tutorials and videos and trying to decide what to do with them. They were pretty popular, but being hosted on multiple sites meant they lacked structure between them and were less useful than they could be. I needed somewhere to put them.

Having looked the options available for hosting tutorials and courses I couldn't find something that fit my requirements. So I committed the #1 programmer mistake of building my own. pythonguis.com was born, and it turned out pretty great.

Built on the Django-based Wagtail CMS it has been extended with some custom apps into a fully-fledged learning management system_._ But it's far from complete. Plans include adding progress tracking, certificates and some lightweight gamification. The goal here is to provide little hooks and challenges, to keep you inspired and experimenting with PyQt (and Python). The site uses a freemium model — detailed tutorials, with an upgrade to buy video courses and books for those that want them.

The availability of free tutorials is key — not everyone wants videos or books and not wanting those things shouldn't stop you learning. Even so, the upgrade is a one-off payment to keep it affordable for as many people as possible, no subscriptions here!

New Tutorials

Once the existing tutorials and videos were up and running I set about creating more. These new tutorials were modelled on the popular multithreading tutorial, taking frequently asked PyQt5 questions and pain points and tackling them in detail together with working examples. This led first to the (often dreaded) ModelView architecture which really isn't that bad and then later to bitmap graphics which unlocks the power of QPainter giving you the ability to create your own custom widgets.

As the list of obvious targets dries up I'll be adding a topic-voting system on site to allow students to request and vote for their particular topics of interest, to keep me on topic with what people actually want.

New Videos

The video tutorials were where it all started, however in the past year these have fallen a little behind. This will be rectified in the coming months, with new video tutorials recorded for the advanced tutorials and updates to the existing videos following shortly after. The issue has been balancing between writing new content and recording new content, but that problem is solved now we have...

New Writers

With the long list of things to tackle I was very happy to be joined this year by a new writer — John Lim. John is a Python developer from Malaysia, who's been developing with PyQt5 for over 2 years and still remembers all the pain points getting started. His first tutorials covered embedding custom widgets from Qt Designer and basic plotting with PyQtGraph both of which were a huge success.

If you're interested in becoming a writer, you can! You get paid, and — assuming you enjoy writing about PyQt — it's a lot of fun.

New Types of Content

In addition to all the new tutorials and videos, we've been experimenting with new types of content on the site. First of all we have been working on a set of example apps and widgets which you can use for inspiration — or just plain use the code from — for your own projects. Everything on the site is open source and free to use.

We've also been experimenting with alternatives short-form tutorials & docs for core Qt widgets and features. The first of these by John covers adding scrollable regions with QScrollArea to your app. We'll have more of these, together with more complete documentation re-written for Python coming soon.

New Year

That's all for this year.

Almost. We're currently running a 50% discount on all courses and books with the code NEWYEAR20. Every purchase gets unlimited access to all future updates and upgrades, so this is a great way to get in ahead of all the good stuff coming down the pipeline.

The same code will give 20% off after New Year. Feel free to share it with the people you love, or wait a few days and share it with people you love slightly less.

Thanks for all your support in 2019, and here's to another great year of building GUI apps with Python!

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

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.

Martin Fitzpatrick

Remaking the classic Atari game ET in 10 lines of SAM Coupé BASIC

Playing

Readable code

PUR 120

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 Snake in 10 lines of SAM Coupé BASIC — Simple Snake game in 10 lines of BASIC

Playing

Readable code

How it works

PUR 80

Bugs

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

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)