Rock-Paper-Scissors Game with Switches and LEDs

I thought it would both be fun and interesting to change the game play on the Raspberry Pi to use push button switches to select the sign and have LEDs indicate a win, lose, or tie for the game. In this project, I also introduce how the Raspberry Pi handles interrupts using the Python language. There is one caveat to this program. It must be started using the following command-line entry:

python prs_with_LEDs_and_Switches.py

The Raspberry Pi system now needs to be set up. The Fritzing diagram is shown in Figure 4-3.

Figure 4-3. Fritzing diagram for rock-paper-scissors game machine

Figure 4-3 is an extension of Figure 3-11, which was used in an expert system demonstration. I added one additional LED and four push button switches to the circuit. The additional LED was connected to pin 27, while the push buttons were connected to pins 12, 16, 20, and 21.

The physical Raspberry Pi setup is shown in Figure 4-4. Notice that I put labels near the LEDs and push buttons to help the user determine what the LEDs indicate and which sign a particular push button enables. The fourth push button exits the program when pushed.

Figure 4-4. Physical Raspberry Pi setup

The push buttons act as inputs that momentarily provide a high level of 3.3V to the pin when pushed. Each of the input pins is also set up to be in a pull-down mode, where an internal resistor at the pin input is connected to ground. This prevents an indeterminate floating state from being applied to the pin. In such a state, a floating pin could “see” voltages ranging from tens of millivolts to as high as two volts, which could trigger a false high on the pin. The actual float voltage is highly variable and dependent on the local potential field surrounding the pin. Connecting a pull-down resistor avoids all that nasty trouble. And the good news is that the pull-down resistor is actually configured via a software command, which I discuss after I show you the following code listing.

prs_with_LEDs_and_Switches.py

import RPi.GPIO as GPIO
import time
from random import randint

# Setup GPIO pins
# Set the BCM mode
GPIO.setmode(GPIO.BCM)

# Outputs
GPIO.setup( 4, GPIO.OUT)
GPIO.setup(17, GPIO.OUT)
GPIO.setup(27, GPIO.OUT)

# Ensure all LEDs are off to start
GPIO.output( 4, GPIO.LOW)
GPIO.output(17, GPIO.LOW)
GPIO.output(27, GPIO.LOW)

# Inputs
GPIO.setup(12, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(16, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(21, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(20, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)

global player
player = 0

# Setup the callback functions
def rock(channel):
    global player
    player = 1  # magic number 1 = rock, pin 12

def paper(channel):
    global player
    player = 2  # magic number 2 = paper pin 16

def scissors(channel):
    global player
    player = 3  # magic number 3 = scissors pin 21

def quit(channel):
    exit()      # pin 20, immediate exit from the game

# Add event detection and callback assignments
GPIO.add_event_detect(12, GPIO.RISING, callback=rock)
GPIO.add_event_detect(16, GPIO.RISING, callback=paper)
GPIO.add_event_detect(21, GPIO.RISING, callback=scissors)
GPIO.add_event_detect(20, GPIO.RISING, callback=quit)

# computer random pick
computer = randint(1,3)

while True:

    if player == computer:
        # This is a tie condition
        GPIO.output(27,GPIO.HIGH)
        time.sleep(5)
        GPIO.output(27, GPIO.LOW)
        player = 0
    elif player == 1:
        if computer == 2:
            # Player loses, paper covers rock
            GPIO.output(17,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(17, GPIO.LOW)
            player = 0
        else:
            # Player wins, rock dulls scissors
            GPIO.output(4,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(4, GPIO.LOW)
            player = 0
    elif player == 2:
        if computer == 3:
            # Player loses, scissors cuts paper
            GPIO.output(17,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(17, GPIO.LOW)
            player = 0
        else:
            # Player wins, paper covers rock
            GPIO.output(4,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(4, GPIO.LOW)
            player = 0
    elif player == 3:
        if computer == 1:
            # Player loses, rock dulls scissors
            GPIO.output(17,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(17, GPIO.LOW)
            player = 0
        else:
            # Player wins, scissors cuts paper
            GPIO.output(4,GPIO.HIGH)
            time.sleep(5)
            GPIO.output(4, GPIO.LOW)
            player = 0

    # another random pick for the computer
    computer = randint(1,3)

One thing that you should immediately notice is that I only used numbers to represent the signs in this game version. There is no need for actual string names because the LEDs show the result of the round and the push buttons are already clearly labeled. However, I did identify what these “magic” numbers represent by using comments with the code listing. I use the magic to represent any number that is used to represent something else. Without a comment or other identifying means, it does become a magic trick to figure what an isolated number in a program is supposed to represent. Unfortunately, more than a few developers still resort to using magic numbers in their programs—a practice I highly suggest you avoid unless you comment them, but then they are no longer magic.

The logic in the preceding program is exactly the same as what was presented in the first version of the program. Yet, there are big differences in the input and outputs, which now use push buttons and LEDs. I will discuss the LED output first since you have already seen it in the expert system demonstration. The pin number scheme is first selected, which is still going to BCM because it matches the T Pi Cobbler pin designations. The pins selected to be outputs are set up next. Those pins are 4, 17, and 27, which represent win, lose, and tie, respectively. That’s all that’s needed to preconfigure the outputs. Turning on an output is done using this command:

GPIO.output(n, GPIO.HIGH)  # where n = pin number

You should also notice that I followed each LED output command with this command:

time.sleep(5)

This forces the Python interpreter to pause for five seconds, which allows the user to easily recognize which LED is lit. Without a pause, the LED will light and extinguish so quickly that you could never see it. That condition would likely puzzle a lot of new programmers who expect to see a lit LED, but never do. The program was probably functioning as desired but the new programmer neglected the reality of a real-time clock cycle, such that the LED stayed on for only microseconds—far too brief a time to detect with the human eye.

Now on to the input pins and the interrupt discussion.

Interrupts

There are two principal ways to handle pin inputs: polling and interrupts. Polling, as the name suggests, simply periodically checks on a pin state. It must be implemented in a loop to work. The following code snippet shows a way to check on a pin status:

if GPIO.input(n):           # where n = pin number
    print('Input was HIGH')
else:
    print('Input was LOW')

Polling is much slower than using interrupts, because all the code in a loop must be executed. It is possible to miss a button press if the program takes a relatively long time to complete each loop, especially if there are any pause statements in the loop.

Interrupts, on the other hand, are practically immediate, independent of what is going on in the main program, looping or not. Interrupts take advantage of a hardware subsystem contained within the ARM microprocessor called the interrupt controller. Figure 4-5 is a very simplified diagram of an interrupt controller that has three interrupt sources: a push button, a serial input, and a clock input. The push button interrupt source is pertinent in this project.

Figure 4-5. Interrupt controller

Figure 4-6 is a logic flow diagram that clearly shows the sequence of actions when an interrupt occurs.

Figure 4-6. Interrupt logic flow diagram

Normally, the microprocessor fetches and executes one instruction after another while running the main program. When an interrupt occurs, which I will now call an event to conform to the Python language terminology, a jump is made to an interrupt service routine (ISR) , as shown in Figure 4-6. And just to further confuse you, ISRs are known as callback functions in Python. The interrupt controller automatically saves the address of the next executable instruction, as well as several other parameters, which is known as saving the processor state. The callback function is run next, and when that is completed, the interrupt controller reloads the processor state and resumes exactly from the point it was when interrupted. All of this action only takes microseconds to complete and is much faster than polling.

There are several steps that must be done in Python to set up interrupts. First, the appropriate pin to receive the interrupt must be set up. I will use the rock push button as an example. This next statement sets pin 12 as an input with a pull-down resistor configured for the reasons I discussed earlier:

GPIO.setup(12, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)

Next, the interrupt source must be identified and linked to a callback function. The following statement does it for the rock-signal push button:

GPIO.add_event_detect(12, GPIO.RISING, callback=rock)

Finally, the callback function must be defined. For the rock signal, this function is

def rock(channel):
    global player
    player = 1  # magic number 1 = rock, pin 12

Notice, that the word channel must be used as an argument in the function definition. This is just a peculiarity of the Python language.

Also notice that I used the word global in the function definition, which specifies that the player variable was global or available to all portions of the program, whether or not it was in the function or the main program. I normally do not like to use globals because they break the object-oriented principle of encapsulation, but in this case, it seemed appropriate to minimize code duplication and to increase program efficiency. You also need to identify player as a global in the main program.

The last new program feature is the exit push button, which causes it to immediately quit the Python interpreter. This is the callback function:

def quit(channel):
    exit()      # pin 20, immediate exit from the game

Everything else in the program is straightforward or was discussed previously.

There is no screenshot that I can show of this program running because the inputs are manual push button activations and the outputs are LEDs being lit. I can just assure you that everything functioned as anticipated.

The next game that I discuss is Nim.

Nim with LCD and Switches

This Nim version uses push button switches to enter the number of sticks to be removed. It uses an LCD to display when the human player should press a push button and to show the number of remaining sticks. The push buttons are connected to Python callback functions, as was done with the automated rock-paper-scissors (rps) game version. In fact, I used a very similar push button circuitry in the prs game. I did have to change the pins used with the push buttons to accommodate the LCD display interconnections. The LEDs in the prs game are no longer needed because they are replaced by the 16 × 2 LCD display.

The Fritzing diagram for the automated Nim setup is shown in Figure 4-10.

Figure 4-10. Fritzing diagram for the automated Nim game

There are obviously too many wiring connections in this setup than can be properly shown in a Fritzing diagram. Therefore, I have provided both a schematic showing the LCD-to–Pi Cobbler interconnections and a pin list showing all the system interconnections. Figure 4-11 is the LCD module–to–Pi Cobbler schematic.

Figure 4-11. Schematic of Pi Cobbler–to–LCD module

Table 4-5 is the pin list detailing all the board interconnections. Note that the LCD pin designations start at 1 at the left and go to 16 at the far right for the LCD orientation, as shown in the Fritzing diagram. The potentiometer is oriented “upside-down,” which places the pins on top. The left pin connects to ground, the middle pin to LCD pin 3, and the right pin connects to 5V.

There are a lot of jumpers to connect in this setup, so be especially carefully when wiring the solderless breadboard. I recommend that you use a separate power rail for the 5V supply that should be located on the top of the breadboard if you are using a horizontal orientation for the board. Pay particular attention that you do not connect any 5V source to a Raspberry Pi input because it will surely destroy that input pin. The GPIO inputs are strictly limited to a maximum level of 3.3V, anything higher will burn out that input pin and likely cause further damage to the Raspberry Pi core.

Figure 4-12 shows the complete physical setup with each of the push buttons’ functions labeled.

Figure 4-12. Physical setup for the automated Nim game

The program that controls this hardware is named automated_nim.py. It is based on the previous program, except all the inputs are now accomplished with callback functions and an LCD display is used to show the game status. I felt it was appropriate to first discuss how the LCD display functions with the Raspberry Pi before actually getting into the main program.

LCD Display

I will first acknowledge that most of the material in this section is based on a very good Adafruit tutorial by Tony DiCola available at https://learn.adafruit.com/character-lcd-with-raspberry-pi-or-beaglebone-black/overview .

Inexpensive 16 × 2 or 16 × 4 LCDs with 16 connector pins are most likely using a Hitachi HD44780 controller or a generic equivalent. The LCD uses a parallel interface, meaning that you need multiple wires from the Raspberry Pi to control it. This setup uses only four data pins and two control pins. This configuration is known as the LCD nibble input mode. The other mode is where a full byte, or eight bits, is transferred each time there is a new character input to the LCD. Obviously, the nibble mode is slower than the byte mode, but for this application, the speed difference is not apparent. The Raspberry Pi is only sending data to the display; it is not reading any data. This means that that you do not have to be concerned about any 5V pulses being sent to the more sensitive Raspberry Pi input pins that only have a 3.3V maximum voltage input, as I mentioned earlier.

The register select pin #4 on the 16-pin LCD header has two uses. When pulled low, the Raspberry Pi can send control commands to the LCD, such as change to a designated character position or clear the screen. This is mode is referred to as writing to the instruction or command register. When the register select pin is set high, the LCD controller goes into a data mode and accepts data to display on the screen.

The read/write pin #5 is grounded, because only data is to be written to the LCD for this setup.

The enable pin #6 is toggled as necessary to write data to the input registers that eventually display on the screen.

After you wire the LCD, push button switches, and potentiometer, you need to load a special Python library that allows the LCD display to work with the Raspberry Pi. This library was created by the clever folks at Adafruit, who have a lot of libraries to support all sorts of devices and sensors. The procedure I go through next is also applicable to loading most other specialty Adafruit libraries.

Loading the Adafruit LCD Library

You need the Git application to load the library because Adafruit uses github.com to store all of its libraries. Enter the following commands to install Git:

sudo apt-get update
sudo apt-get install git

Once Git is installed, you can now download the LCD library. This download process is called cloning. It results in new directory named Adafruit_Python_CharLCD created in your home directory. Enter this command:

sudo git clone git://github.com/adafruit/Adafruit_Python_CharLCD

The newly created directory contains all the required files for the next step, which is to set up the library. The setup process is long and involved; however, there is a simple setup script provided to automate the whole process. Enter the following commands to set up the library:

cd Adafruit_Python_CharLCD
sudo python setup.py install

Figure 4-13 shows the beginning and ending of the install process. Overall, there are more than 70 separate actions taking place in the installation, including downloading and building multiple dependencies.

Figure 4-13. LCD library installation script execution

Now, you should test the both the hardware and the software installations to verify that everything is working properly.

LCD Test

The test program named char_lcd.py should be located in the examples subdirectory of the Adafruit_Python_CharLCD directory that was created after the Git clone operation completed. Go to the examples directory and enter this command:

python char_lcd.py

If everything is wired correctly, and all the libraries are installed properly, you should see the display as shown in Figure 4-14.

Figure 4-14. Result of running the char_lcd.py program

If you do not see this display, please recheck all the wiring because it is pretty easy to misplace a jumper insertion point or connect to the wrong pin on the Pi Cobbler or LCD module. As I mentioned earlier, most faults are normally wiring or interconnection mistakes.

Assuming that the LCD test was successful, it is now time to consider the main Nim program.

automated_nim.py

This program has been substantially changed from the previous Nim program because of the need to incorporate callback functions and LCD display routines. I have also incorporated some AI logic into the program: the computer opponent now uses the game theory n mod 4 = 1 equation to help in its stick selection, in addition to using the random number generator when the optimal pick is not achievable.

automated_nim.py listing

!/usr/bin/python

# import statements
import random
import time
import Adafruit_CharLCD as LCD
import RPi.GPIO as GPIO

# Start Raspberry Pi configuration
# Raspberry Pi pin designations
lcd_rs        = 27
lcd_en        = 22
lcd_d4        = 25
lcd_d5        = 24
lcd_d6        = 23
lcd_d7        = 18
lcd_backlight =  4

# Define LCD column and row size for a 16x4 LCD.
lcd_columns = 16
lcd_rows    =  4

# Instantiate an LCD object
lcd = LCD.Adafruit_CharLCD(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows, lcd_backlight)

# Print a two line welcoming message
lcd.message('Lets play nim
computer vs human')

# Wait 5 seconds
time.sleep(5.0)

# Clear the screen
lcd.clear()

# Setup GPIO pins
# Set the BCM mode
GPIO.setmode(GPIO.BCM)

# Inputs
GPIO.setup(12, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(13, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(19, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)
GPIO.setup(20, GPIO.IN, pull_up_down = GPIO.PUD_DOWN)

# Create the global variables
global player
player = ""
global humanTurn
humanTurn = False
global stickNumber
stickNumber = 21
global humanPick
humanPick = 0
global gameover
gameover = False

# Set up the callback functions
def pickOne(channel):
    global humanTurn
    global humanPick
    humanPick = 1
    humanTurn = True

def pickTwo(channel):
    global humanTurn
    global humanPick
    humanPick = 2
    humanTurn = True

def pickThree(channel):
    global humanTurn
    global humanPick
    humanPick = 3
    humanTurn = True

def quit(channel):
    lcd.clear()
    exit()      # pin 20, immediate exit from the game

# Add event detection and callback assignments
GPIO.add_event_detect(12, GPIO.RISING, callback=pickOne)
GPIO.add_event_detect(13, GPIO.RISING, callback=pickTwo)
GPIO.add_event_detect(19, GPIO.RISING, callback=pickThree)
GPIO.add_event_detect(20, GPIO.RISING, callback=quit)

# random selection for the players
playerSelect = random.randint(0,1)
if playerSelect:
    humanTurn = True
    lcd.message('Human goes first')
    time.sleep(2)
    lcd.clear()
else:
    humanTurn = False
    lcd.message('Computer goes first')
    time.sleep(2)
    lcd.clear()

# The AI portion
def computerMove():
    global stickNumber
    global humanTurn

    if (stickNumber-1) % 4 == 1:
        computerPick = 1
    elif (stickNumber-2) % 4 == 1:
        computerPick = 2
    elif (stickNumber-3) % 4 == 1:
        computerPick = 3
    else:
        computerPick = random.randint(1,3)

    if stickNumber >= 4:
        stickNumber -= computerPick
    elif (stickNumber==4) or (stickNumber==3) or (stickNumber==2):
        stickNumber = 1
    humanTurn = True

# The human portion
def humanMove():
    global humanPick
    global humanTurn
    global stickNumber
    while not humanPick:
        pass
    while (humanPick >= stickNumber):
        lcd.message('Number selected
')
        lcd.message('is >= remaining
')
        lcd.message('sticks')
    stickNumber -= humanPick
    humanTurn = False
    humanPick = 0
    lcd.clear()

def checkWinner():
    global gameover
    global player
    global stickNumber
    if stickNumber == 1:
        msg = player + ' wins!'
        lcd.message(msg)
        time.sleep(5)
        gameover = True

def resetGameover():
    global gameover
    global stickNumber
    gameover = False
    stickNumber = 21
    return gameover

# This module controls the overall game play
def game():
    global player
    global humanTurn
    global gameover
    global stickNumber
    while gameover == False:
        if humanTurn == True:
            lcd.message('human turn
')
            msg = 'sticks left: ' + str(stickNumber) + '
'
            lcd.message(msg)
            humanMove()
            msg = 'sticks left: ' + str(stickNumber)
            lcd.message(msg)
            time.sleep(2)
            checkWinner()
            lcd.clear()
        else:
            lcd.message('computer turn
')
            computerMove()
            msg = 'sticks left: ' + str(stickNumber)
            lcd.message(msg)
            time.sleep(2)
            checkWinner()
            lcd.clear()

    if gameover == True:
            lcd.clear()
            playAgain()

# As the name suggests; play again?
def playAgain():
    global humanPick
    lcd.message('Play again?
')
    lcd.message('1 = y, 2 = n')

    # This loop is needed to idle while waiting for a button press
    while humanPick == 0:
        pass
    if humanPick == 1:
        lcd.clear()
        resetGameover()
        game()
    elif humanPick == 2:
        lcd.clear()
        lcd.message('Thanks for 
')
        lcd.message('playing the game')
        time.sleep(5)
        lcd.clear()
        exit()

# This function call kicks off the game play
game()

I believe you will find that defeating the computer in this program is quite difficult, which differs sharply from the earlier, more naive Nim program. Figure 4-15 is a photograph of the LCD screen captured while I was playing a round with the computer.

Figure 4-15. LCD display during round play

This automated Nim program is the final project in this chapter. There are more Python games readily available in the Jessie Linux distribution that you may wish to investigate. They can be found in the main X window GUI that is shown in Figure 4-16.

Figure 4-16. Additional Python games

These games are curtesy of Al Sweigert, whose website is at www.inventwithpython.com . At this website, you may freely download a 347-page e-book entitled Making Games with Python & Pygame, in which Al describes, in detail, how the games listed in Figure 4-16 function. It is highly recommended for those readers interested in taking the next step in Python game development beyond what I have discussed in this chapter.