RPi Minecraft + Python Introduction


Interact with Minecraft using the Python programming language and Minecraft’s application programming interface(API).

What You Will Learn:

  • Basic Python Programming
  • Use of the Minecraft API

What is an API?

To put it simply an API is a well defined method of interacting with some kind of software.  Think of it like the rules to a game, the rules dictate how the game is played and how you are able to interact with the game state.

What is Python?

Python is an interpreted programming language that is designed to be easy to learn and easy to use.  Python has many available libraries for the Raspberry Pi and is a very useful tool on the platform. Keep in mind that python uses white space (spaces, tabs, etc) to format and organize it’s instructions, take close care when typing to avoid these sometimes unobvious mistakes.

Getting Started:

Open a terminal either clicking the icon on the top bar or using the keyboard shortcut CTRL+ALT+t.

We are going to make a folder to store help organize the code we will be writing.  Enter the following into a terminal

mkdir ~/code

The mkdir command creates a new directory at the specified location, in this case “~/code”.

The “code” directory is created at the “~/” location ~ or tilde is a shortcut for the home directory.  We can verify the success of the command by entering


In the terminal (this command lists all files and directories), or using a file explorer.

Next, open Thonny Python IDE by navigating to the Raspberry Pi icon in the upper left side of the desktop, click on Programming  and look at the bottom of the list for Thonny Python IDE.

Click on File and select New.

Click on File and Save As “minecraft_python.py” in the code folder we created earlier(/home/pi/code).

Now we are ready to start programming in Python.

Into your empty Python file type

import mcpi.minecraft as minecraft
import mcpi.block as block
from time import sleep

The “import” keyword load a specific code module.  The “as” keyword allows you to rename a code module to something else.  The “from” keyword allows you to load a submodule as it’s own module.

Currently this python program does nothing exciting however lets learn how to execute the program. You can either use they keyboard shortcut F5 or click on the green play icon.

After program execution the shell at the bottom of the window should have some lines of text appear, however nothing should else should happen.

Now type the following into your program

mc = minecraft.Minecraft.create()

mc.postToChat("Hello, world!")

The first line creates an object that is connected to running an instance of Minecraft.  Setting it equal to mc lets us access the Minecraft game using mc within the code. The second line uses the mc object and a method “postToChat” to send text to the games chat.  The third line delays the program for the specified number of seconds, in this case 5 seconds.

Before running the code this time, we need to open Minecraft and enter a new world.  Click on the Raspberry Pi icon in the upper left, click on Games and then Minecraft Pi.

Once Minecraft is open, click Start Game then join a preexisting world or Create New.  

Using the tab key to free your mouse from the Minecraft window, run the code and switch back to the Minecraft window.  “Hello, world!” should appear in the chat.

Going back to the code, type in the following

playerPos = mc.player.getPos()
mc.player.setPos(playerPos.x, playerPos.y + 50, playerPos.z)
mc.postToChat("Don’t look down!")

The position of the players head is stored in the playerPos object.  The players new position is then set relative to the previous position (In Minecraft you stand on the XZ plane with the Y axis being vertical).


Running this code will in addition to the previous action of sending text to the chat but then teleport the player 50 blocks vertically of their current position.


It is ideal to type in code whenever possible as it helps with learning however this next section is rather large and copy-paste will make quick work.

playerTilePos = mc.player.getTilePos()
blockBelowPlayerType = mc.getBlock(playerTilePos.x, playerTilePos.y - 1, playerTilePos.z)
mc.setBlock(playerTilePos.x + 1, playerTilePos.y + 1, playerTilePos.z, blockBelowPlayerType)
mc.setBlock(playerTilePos.x, playerTilePos.y + 1, playerTilePos.z + 1, blockBelowPlayerType)
mc.setBlock(playerTilePos.x - 1, playerTilePos.y + 1, playerTilePos.z, blockBelowPlayerType)
mc.setBlock(playerTilePos.x, playerTilePos.y + 1, playerTilePos.z - 1, blockBelowPlayerType)
mc.postToChat("Trapped you")

mc.setBlock(playerTilePos.x + 1, playerTilePos.y + 1, playerTilePos.z, block.AIR)
mc.postToChat("Be free!")

Notice that a different method is called to identify the position of the tile the player is standing in.  The setBlock method allows a single block specified with an (X,Y,Z) coordinate and a block

After running the code try to look back and see if you can identify what each line is doing.

Now add the following to your code.

mc.setBlocks(playerTilePos.x - 25, playerTilePos.y - 1, playerTilePos.z - 25, playerTilePos.x + 25, playerTilePos.y - 1, playerTilePos.z + 25, block.DIAMOND_BLOCK)
mc.postToChat("Now that's a big diamond floor!")

Notice that the setBlocks method unlike the setBlock method can take a range of X, Y, and Z coordinates.

Running the code this time in addition to the previous actions will change the blocks in a 50 x 50 x 1 shape 1 block beneath the players feet.

Whats Next?

  • Modify the code, move the player in different directions.  
  • Add additional blocks to the trap.
  • Try changing DIAMOND_BLOCK to another block type, a list of the block types can be found in the API documentation, about halfway down the page
  • Inspect the API documentation to see how else you can interact with Minecraft using Python

Article and code adapted from source

RPi: Editing Text files and Python Scripts with Raspbian

Getting Started

There are a myriad of ways to edit text files and code built into the Raspbian distribution; several even inside the terminal. But here we will cover some of the easier to use graphical programs.

It’s important you know your way around the terminal before continuing, please see the terminal tutorial -> here

Editing config files with leafpad

Leafpad is a lightweight notepad-like text editor that is bundled with Raspbian; we will use it here to edit simple config files in the file system.
For example the led ring tutorial directs us to edit the /boot/config.txt and comment out some lines.
To do this navigate to the /boot/ directory in the terminal; and then run ‘sudo leafpad config.txt’, this is similar to other commands you have seen taking a path as an argument, the important difference is the ‘sudo’ prefix which tells the terminal to run this command as a ‘super user’. This allows us to overwrite important system files and access gpio pins ect. You’ll have to use it often but you should still be careful.

We get an editor window like notepad on windows, we can insert a ‘#’ before dptparam to comment it out, and then save with control s
after exiting the editor you will regain control of your terminal.

Editing and running python scripts with Thonny

Next we can use a slightly complicated editor, Thonny is specifically for python ‘.py’ files and has some features that make debugging scripts easier.
Thonny can be found in the menu in the top left corner, or again opened from the terminal with ‘sudo thonny’.
Most scripts accessing the GPIO require sudo powers to work correctly, so its best to get used to running it as sudo.
You open a file to edit by navigating to it in the thonny gui; like notepad on windows.

We can enter python scripts line by line into the main window, and at any moment run our script with F5 or the gui button (green arrow).
Here is what it looks like to run a simple program inside thonny.
note the output in the lower window, this is the result of pressing F5 or the run button

RPi Sense HAT+Minecraft

The Sense HAT was developed by the folks at Raspberry Pi as an add on board that contains a number of sensors and a LED display. In this lesson we can demonstrate how to use the Sense HAT in conjunction with Minecraft to visualize real world data and control the LED Screen.

I use this lesson primarily to get students excited about the connection between a sensor and the way that we can visualize data through Minecraft.  This worksheet from the folks at the Raspberry Pi foundation is an excellent resource. In the latter portions of the lesson it goes into methods of collecting data from the Sense HAT and displaying it within the Minecraft world.


Follow along with the Sense HAT installation and the first several worksheets of this project.

4. Github Intro

Github is known as a repository for cool programs that can be used in all sorts of ways on your Pi. In this lesson we will learn how to install programs from Github using the terminal.

First lets install a program that can do screen captures. Something that is handy when students have created something amazing in their Minecraft world.

Lets follow the instructions for taking screenshots provided by Martin O’Hanlon.


Here is a video going through the process.

Students will be really excited when they learn to download programs that can run within their Minecraft world. Lets go back to Martin’s API tutorial and have students select one of the first three items, clock, cannon, or snake video game.


In each of these examples, there is a section of code that should be copied into the terminal. When enter is pressed on the keyboard, a bunch of code will appear and a new program file will be placed in the home directory on the Pi

Have students navigate to the file folder and open the file with the .py extension by right clicking on the file and selecting open with python 2 from the drop down menu.  If the program is run while Minecraft is open it will place an exciting new feature in the Minecraft world. This will hopefully trigger a desire to try downloading other python programs to modify their Minecraft worlds.

RPi Python: LED Ring Clock WS2812


Have Raspbian Stretch installed, running, and connected to the internet.
You should refresh on how to easily edit files and navigate the filesystem using a terminal in these tutorials:
Terminal Intro
Editing Files Intro

Next some configuration,
To correctly output PWM to control the LED ring we first need to disable the native Raspberry Pi soundcard, to do this navigate to /boot/config.txt and comment out the line ‘dtparam=audio=on’

# Enable audio (loads snd_bcm2835)

^ so it looks like this.

Next step is to install some utilities we will need for setting up our led control libraries and the python environment to talk to them; open a terminal and enter

apt-get install gcc make build-essential python-dev git scons swig

this installs some compilers and utilities we will use in the next step

Next navigate to the folder where you want to setup your LED script in a terminal, use ‘mkdir’ to create a new directory if you want; here we will download the library using git
For more help on navigating and creating directories from within the terminal, see this article -> click here

git clone https://github.com/jgarff/rpi_ws281x

Enter the new rpi_ws281x directory and use the ‘scons’ utility we installed earlier to start building the library into something we can use:

sudo scons

Next enter the python directory, and run the setup and build scripts:

sudo python setup.py build install


First off here is a link to the finished project as a reference
To test it, download the file, rename to clock.py, and run as sudo python clock.py

Next to writing the actual script itself…
The first step is a bunch of boilerplate, like telling our library how many LEDs we have and what pin to use ect.
We start off by importing the libraries to control the leds, and read the date and time from the system

from neopixel import *
import time
import datetime

next are the constants that tell which pin to use, and which kind of led ring we are using

LED_COUNT          = 12          # Number of LED pixels.
LED_PIN            = 18          # GPIO pin connected to the pixels (18 usesPWM!).
LED_FREQ_HZ        = 800000  # LED signal frequency in hertz (usually 800khz)
LED_DMA            = 10  # DMA channel to use for generating signal (try 10)
LED_BRIGHTNESS = 10         # Set to 0 for darkest and 255 for brightest
LED_INVERT         = False   # True to invert the signal (when using NPN transistor level shift)
LED_CHANNEL        = 0           # set to '1' for GPIOs 13, 19, 41, 45 or 53
LED_STRIP          = ws.WS2811_STRIP_GRB   # Strip type and colour ordering


As a brief overview, the important ones for us are:
LED_COUNT: the number of LEDs to try and address, if you have a bigger led ring than normal you might change this; 12 is for the one we gave you

LED_PIN: here we use 18; other pins might be tricky so its probably best to stick with 18

LED_BRIGHTNESS: on full brightness the leds can be super super bright, so we lower it all the way down to 10. Wear sunglasses if you turn it up

Finally with strip we setup the strip using all the constants we just defined.


Now we can actually start writing functions and logic for our program. Python scripts usually execute straight from top to bottom in sequential order; but we can essentially jump around our control flow using functionsFunctions take arguments, do things based on these arguments and then exit back to where they were called.

We’ll start with utility functions that will make controlling the ring easier later, before we write the actual clock part. (remember to use tabs for indentation levels).
We start with a function to clear all the leds, essentially turning them all off

def clear (strip):
 for i in range(LED_COUNT):

Let’s go through this function line by line: First we define the function and give it a name ‘clear’, followed by a list of arguments it takesLet’s go through this function line by line:

def clear (strip):

 Next we start a loop to address all the leds, this pattern will appear alot so pay attention!

for i in range(LED_COUNT):

Notice we use the LED_COUNT variable we named earlier, the loop starts i at 0, and then runs its block over and over until ‘i’ reaches the LED_COUNT value


Here we actually start setting the led colors, we gave this function an argument called ‘strip’ and here its accessing some functionality that the ‘strip’ object holds. In this case ‘setPixelColor’. The ‘setPixelColor’ function demands a pixel number and a color as its arguments so that’s what we give it. We create a color out of R G B values (red green blue) using the ‘Color’ function.


Finally we actually get the leds to update on the physical ring.

And that’s the end of our first function!

Next we’ll make a ‘fill’ function which does almost the same thing; except instead of setting all the leds to off it’ll set them to a color we give as an argument.

The new function will follow the same basic pattern as our old one.

def fill (strip, pixel, color):
 for i in range(pixel):

If you compare this and the old function side by side it should be easy to see how they match up and differentiate.

Now we can actually test out our functions and make sure they work.If you compare this and the old function side by side it should be easy to see how they match up and differentiate.

On the line below our functions we can start writing code that will actually execute.


We’ll go over the first few lines to get an idea of how it works:


First we use the ‘begin’ method on our strip to get it ready for any commands


Next we actually call our fill command from earlier, sending it the strip, the number of pixels we want, and a color.


Next we wait for half a second so we get a chance to admire our work.


We repeat the process again for another flash, this time a different color.  Of course it would be more impressive if it flashed more than twice, but we don’t want to just keep copying and pasting the same function calls over and over either. And eventually we want our clock to be running indefinitely not just for a few seconds; so we will setup an infinite loop.


When running this script, you can use Control-C to interrupt and exit the program.A while loop repeats everything in its block until the statement we give it isn’t true; ‘True’ is always true so in this case it just loops forever.

Otherwise it’ll just keep flashing your led ring forever!.

Now we have some nice utility tools setup we can actually start writing the clock itself.

First we need to get the time! Luckily we imported the time library earlier.

So start off by erasing our While loop from earlier, because we’ll be writing another one.

 now = datetime.datetime.now()

Below our other two functions but above our while loop we’ll put our clock function.Here we fill a variable called ‘now’ with the current time every .5 seconds, but we don’t do anything with it yet. For that we need another function.

def clock (strip, now):
 hours = now.second%2
 hourPixel = (now.hour % LED_COUNT) + 1
 minutePixel = (now.minute / (60/LED_COUNT) % LED_COUNT) + 1

 hourColor = Color(255,0,0)
 minuteColor = Color(0,0,255)

 if (hours):

hours = now.second%2This turned out to be a pretty simple function so ill go over it section by section.
The most criptic part is the first line:

This is where we work out if we’ll show the hour or the minute hand; the modulo operator is explained in more depth below but basically we are testing if the time in seconds is an even number or not. If it it’s even we set hours to 0 (false) and if it’s odd we set hours to 1 (true).

Next we calculate the hour and minute pixels; which again is explained in the last section below.

hourColor = Color(255,0,0)
minuteColor = Color(
Here we set the colours we want to use for the hour and minute hands using RGB values

if (hours):
An if statement runs its block of code only if the expression its given is true, the hours variable is set if the seconds are even remember, so every other second we choose to display the hours or the minute hand.
Then we call our fill function from ealier with the desired results.

Finally we put our clock function in our infinite loop from earlier, and our clock is done!

 now = datetime.datetime.now()

And here is the final project again to help fix any errors in your own:Remember to run the script as sudo, like at the start with the strandtest.py example!


Calculating hourPixel and minutePixel:

Looking back over our long clock() function, the most complicated part is the ‘hourPixel’ and ‘minutePixel’ logic; so i’ll go over them in depth here.

hourPixel = (now.hour % LED_COUNT) + 1

hourPixel is a variable which holds a number, the number being which pixel we want to illuminate upto to represent the hour hand of the clock.
We start off with the hour in a 24 hour clock format from now.hour

So if it was 2pm the now.hour would equal 14.

To emulate a 12 hour analog clock we need to convert 14 down to 2.

The ‘%’ operator called ‘modulo’ returns the remainder after doing an integer division; this is very useful for testing if a number if perfectly divisible (the remainder would be zero) and for creating ‘circular numbers’ which never pass a certain value.

If we look test out the modulus operator we can see the pattern:

1 % 12 == 1

2 % 12 == 2

3 % 12 == 3

11 % 12 == 11

12 % 12 == 0 (perfect divisible)

13 % 12 == 1

14 % 12 == 2

So if we enter ‘13’ hours (1pm) into our modulo operator we get a nice conversion straight to 12 hour time (1).

Because our led ring is addressed from 1 instead of 0, (lighting up the 0th led doesn’t work with this library) we add 1 to the result.

So a straight conversion from 13 hours to 1pm, turns into the second led on the ring.

Leaving us with our final algorithm

hourPixel = (now.hour % LED_COUNT) + 1

The math works in the same way but with slightly more complicated variables for the minutePixel algorithm, it’s a good exercise to try and work out how it works yourself.

minutePixel = (now.minute / (60/LED_COUNT) % LED_COUNT) + 1

Further Exercise Ideas:

  • Change the colour of the hands depending on if its AM or PM
  • Add a seconds hand to the clock
  • Display the hours and minutes hand simultaneously with different colours for overlapping areas (see github for a hint!)
  • Make a stopwatch
  • Make a counting down timer with minutes and seconds
  • A rainbow effect on the hands

RPI Python: DHT-11 Temp / Humidity


Readers should be familiar with navigating using the terminal and editing / running python scripts.
Tutorials are available here:
Terminal Intro
Editing Files Tutorial

Hardware setup:

Carefully observe the ports and connect the positive line to the 5v, negative to ground, and the data out line to pin-14 also known as TXD on the raspberry pi GPIO.

Software Setup:

Step one is to download the DHT-11 Python library, which is very small and simple to use

Navigate to whatever directory you want in the terminal and use

git clone https://github.com/szazo/DHT11_Python

To download the library.

Then navigate into the directory with cd, and look around with ls

We can already run the example dht11_example.py with

sudo python dht11_example.py

You should see the temperature and humidity displayed on the screen every few seconds.

Use Ctrl+c to kill the process and get back to the terminal.

Next we can move on to writing our own program that uses the sensor.
If you need to see an example, here is the full project we will be writing in this article finished.

First we need some boilerplate

import RPI.GPIO as GPIO
import dht11
import time

#warmup our GPIO pins 

#get ready to read data with pin 14 
instance = dht11.DHT11(pin=14)

Next we can start writing our own code. Similar to the clock tutorial we will use a infinite loop to keep our code going

while True:
result = instance.read()
if result.is_valid():
 print("Temperature: %d C" % result.temperature)

Our code actually does less than the dht_11 example, but it’s a bit simpler.

result = instance.read()

First we store our input from the sensor in the ‘result’ variable

if result.is_valid():

Next we use an if statement to only proceed if the result is valid

print("Temperature: %d C" % result.temperature)

In our if block we print the temperature using the print function, the ‘%d’ acts as a placeholder for a number (digits), followed by a list of variables to fill the placeholders

print("number %d %d" % (1, 2))

For example would print “number 1 2” to the terminal

Our output should look something like

"Temperature: 20 C"

After exiting the if block we wait for a full second before running the loop again


Remember to exit the program while its running use Control-C to escape
Here is the full example code from this tutorial