LED Count Game: Instructions

1. Overview
2. System Configuration
3. Bill of Materials
   • System Configuration
   • Hardware Configuration
   • Software Configuration
4. Part 1 Set of Instructions
5. Part 2 Set of Instructions
6. More Details
   • Configure the R-Pi System
   • Configure the PiRack Board
   • Configure the PiFace Boards
   • Building the LED Electronics
   • Connecting It All Together
   • Building the Switch Electronics
7. Playing the Game
8. Trouble Shooting
9. Further Development Ideas
10. Appendix A - PiFace Digital Board Jumpers
11. Appendix B - PiRack Board Jumpers
12. Appendix C - The Software
    • System Software
    • LED Test Software
    • LED Selection Software
    • Switch Test Software
    • Game Software
13. Appendix D - Basic Electronics Primer
    • Resistors
    • LEDs
    • Wiring the LEDs
14. Terminology
15. About this Document

Overview

This project is about creating a simple game in which a user has to press a button to indicate which column of lights has the greatest number of lit LEDs.  The game will be based upon 4 columns of 8 LEDs (creating a matrix of 32 LEDs).  The game player will be presented with a sequence of configurations: the number and the period during which a guess can be will be configurable as part of the game set-up.  The system will report the total number of correct answers and missed attempts.  The project is developed in two phases of increasing complexity.  The two phases are:

• Phase 1: Basic LED Display – creation of the basic hardware/electronics solution to drive the set of LEDs from software on the R-Pi;
• Phase 2: LED Count Game – enhancement of the Base solution to create the full game in which a user identifies the column with the most lit LEDs.

This project is aimed at people who have limited experience of using the R-Pi and programming. To successfully complete the project some simple electronics must be built which includes soldering of wires and components. The objectives for this project are to:

• Learn how to use together the R-Pi Model A/B, the PiRack and multiple PiFace Digital boards.  The developer will learn how to combine these boards at both the hardware and software levels, including controlling the output ports and the input ports;
• Once this basic game has been created, there are several directions in which the game can be further enhanced by a developer.  For example, the software/hardware can be enhanced to support multiple players i.e. to set up competition to find the fastest response, etc.

The associated Bill of Materials describes the set of components, hardware and software, required to complete this project. When the complete system is built it will look something like the Figure shown below.

The completed system.

1. System Configuration

The system configuration is shown in Figure 1.1. The basic configuration is:

• R-Pi (Model A/B) - this project can make use of either Model. In the case of Model A, it is recommended that a WiPi is used to provide network connectivity (wireless, IEEE 802.11, via the USB2 port on the R-Pi). Network connectivity makes it easier to download and install the necessary software updates required by the PiFace Digital boards. A USB2 hub is recommended to enable more than two USB devices to be linked to the R-Pi (the R-Pi has two USB ports). It is assumed that the keyboard and mouse are linked via the USB Hub and, if required, the WiPi. The monitor can be linked either via the HDMI interface or the yellow RCA phono connector for composite video output. In this project a PiView connector is used to enable a monitor with a VGA connector to be connected to the R-Pi via the HDMI interface;
• PiRack - a single PiRack is used to connect the PiFace Digital boards to the R-Pi. The PiRack has four GPIO interfaces but a second PiRack can be used and so seven device boards can be added (this means that for this project seven columns of LEDs could be driven by making the appropriate modifications to the hardware and software);
• PiFace Digital - four PiFace Digital boards will be used. Each PiFace digital has eight output ports hence eight external LEDs can be driven by each board. Each PiFace Digital board will drive one column of LEDs;
• LED Matrix and Circuitry - the 32 LEDS must be wired so that they can be driven by the PiFace Digital boards.  Tbe LEDs used in this project have forward voltage of between 1.8V-2.5V.  The PiFace Digital output is 5V and so resistors are required to drop the voltage down as required across the LEDs;
• Switches and Circuitry - the six external switches will all be connected to one PiFace Digital board. These are 'Push-to-Make' switches and they are linked to the ground port on the set of input ports on a PiFace Digital board (in Figure 1.1 the full set of potential switch connections are shown, 32, but only 6 are used on this project).

Figure 1.1 System Configuration

When the complete system is built it will look as shown in Figure 1.2.  The views shown in Figure 1.2 are front (a), back (b), and sides (c) and (d).

2. Bill of Materials

2.1 System Configuration

The architecture is based upon the use of an R-Pi to drive a set of PiFace Digital Boards that are linked to the R-Pi using a PiRack Board. The PiFace Digital boards are used to drive a set of coloured LEDs. The configuration is shown in Figure 2.1 and the key to the alphanumeric labels is provided in Tables 2.1 and 2.2.

Figure 2.1 - System configuration for the 'Bill of Materials'

The associated bill of materials for the system shown in Figure 2.1 is listed in Table 2.1. The items denoted by an '*' are required for the Part 2 development.

Table 2.1 - the Bill of Materials.

Notes

• You may want to increase the quantity of the LEDs and resistors. They are low cost and it is a good idea to get a few extras in case one gets damaged or lost during assembly. Also, 180  Ohm resistors (38K0346) have been specified but you may want ot vary these if the LEDs are too dim;
• The colours of the LEDs can be varied to choice. The design assumes that each column of LEDs is the same colour but this is not a necessity. The size of the LEDs can be changed but take care if selecting ones that require anything greater than a 5V supply. This design takes the 5V supply from the corresponding PiFace Digital board. If a greater voltage is required then a separate power supply to the LED circuitry will be required;
• A suitable soldering kit is required to construct the LED and Switch circuitry on the two circuit boards;
• It is recommended that a wooden base and stand is used to mount the set of LEDs and the switches so that they are easy to see and use (see Figure 1.2 for one way in which these can be used);
  
• A range of tools are required including wire strippers, wire cutters, small thread screw driver, pliers and drill.

2.2 Hardware Configuration

The hardware connectivity is detailed in Table 2.2.

Table 2.2 - Hardware connectivity.

2.2 Software Configuration

The software required to support this project that must be installed on the R-Pi is:

• R-Pi Operating System (Raspian) - this is installed using the NOOBS that comes pre-installed on the R-Pi SD cards.  If NOOBS is not preinstalled it is available at Downloads;
• Integrated Development Environment - IDLE with Python 3.x support with the 'tkinter' modules installed (normally installed as part of Raspian);
• PiFace Digital libraries (make sure you download the PYTHON 3 versions i.e. the download buttons on the right hand-side):-
  • Latest PiFace Common software (v3.1.1) - download from GitHub at https://github.com/piface/pifacecommon/releases
  • Latest PiFace Digitalio software (v2.1.0) - download from Github at https://github.com/piface/pifacedigitalio/releases

NOTE: Do not use any releases other than those above as problems with the software and later releases of these libraries have been detected.  We are working through these problems and will update the documentation and source code once resolved.

3. Part 1 Set of Instructions

The set of instructions for creating the LED Count Game Part 1 are:

1. Configure the R-Pi system in preparation for the creation of the game hardware and software - once the basic components have been connected i.e. the monitor, USB2 Hub, keyboard and mouse and the network connection established (using either a WiPi for wireless access or using the wired Ethernet port) then a number of software-related actions have to be completed. First the SPI driver has to be enabled in the R-Pi operating system and, secondly, the PiFace Digital libraries have to be downloaded (see More Detail);
2. Configure the PiRack board - the configuration of the PiRack is very easy.  The two set of jumpers have to be set appropriately i.e. J1/J2, J3/J4, J5/J6 and J7/J8 set to the 'Default SPI CE' mode, and J9, J10, J11 and J12 to external power supply. With these settings an external power supply for the PiRack must be used (see More Details);
3. Configure the PiFace Digital boards - each PiFace Digital has seven jumpers that are used to set the configuration.  Jumpers J1/J2 are used to enable each PiFace Digital board to be uniquely identified when used with a PiRack board. Jumpers J5/J6 should be removed to disable the output relays (see More Details);
4. Create the LED electronics board - creating the LED board is primarily concerned with attaching the set of LEDs to the circuit board and soldering the power supply wires to the anode pins (the longer pin) of the LEDs and the output port wires to the cathode pins (shorter pin) of the LEDs. First, attach the matrix of LEDs to the circuit boards (this was done by reversing the cicuit board, inserting the LED pins through the board and soldering one pin to the copper side of the board).  A common power wire is now soldered to the anode pins of the LEDs in one column.  The lower end is now soldered to the circuit board and to this one end of a resistor is soldered.  A red power supply wire is now soldered to the other end of the resistor.  An individual black wire is now soldered to each of the anode pins of a LED.  Finally, each black wire is labelled, '0' to '7' with the wire soldered to the bottom LED identified with a '0' and the top with a '7'. This process is repeated for each column of LEDs.  The LED board is now ready (see More Details).  Note that, in this approach, we have used only one resistor per column of LEDs which results in a variation of the light of the LEDs when more than one is switched on.  A better approach is to use one drop down resistor per LED.  When one resistor per LED is used, a resistor is soldered to the anode pin of each of the LEDs and the other end of the resistor is soldered to the common 5V line to which the red wire is also soldered;
5. Connect the LED electronics board to the PiFace boards - the wiring from the LEDs now have to be connected to the PiFace Digital boards.  The wires from each column should be wired to one of the PiFace Digital boards. Connect each of the black wires to one of the Output Ports. For this project the bottom LED of each column is wired to Output Port '0'.  The red wire for each column, the 5V power supply, is now wired to the 5V In/Out port on the PiFace Digital to which the other black wires are connected (see More Details - Figure 5.10a);
6. Connect the PiFace boards to the PiRack (make sure that ALL of the LED and switch wiring to the PiFace Digital boards has been completed otherwise the GPIO connectors may be damaged if the wiring is attempted once the boards have been connected together) - each PiFace Digital is need connected to the PiRack using the GPIO connectors on each board.  The order of the PiFace Digital boards on the PiRack is not critical i.e. the board with the jumpers J1/J2 set to '00' does not have to be a the bottom.  However, the supplied software assumes that the bottom board is '00' and the top is '11' i.e. the label order is from bottom to top. If a different order is used then the game and test sofware will need to be changed appropriately otherwise the visual displays will not be as expected (see More Details);
7. Connect the PiRack/PiFace boards to the R-Pi (again make sure all of the external wires have been connected to the PiFace Digital boards to avoid damaging the GPIO connectors) - the final step is to connect the fully populated PiRack to the R-Pi.  Again this is achieved using the GPIO connectors on the R-Pi and the PiRack (see More Details);
8. Download and run the LED configuration test software - download the LED configuration test software file 'ledconfigtestv1p*.py', written in Python 3, and confirm that the LED board is working correctly.  This software uses a predefined LED test script that tests each individual LED, each column of LEDs and the full set of LEDs (see More Detail);
9. Download and run the LED GUI-based controller software - download the LED chooser software file 'ledchooserv1p*.py', written in Python 3, to control the individual settings of each, and all, LEDs on the LED board.  This software provides a GUI that allows a user to control the setting of any, and all, of the LEDs (see More Detail).

A video, some 13 minutes long, demonstrating the construction of the part 1 system build is shown in Video 1.  This video is available in low resolution (a) and high resolution (b) and (c) - the high resolution video, split into two parts each of 7 minutes duration, will require at least a 3.5Mbps broadband data rate to view.

Video 1 - The part 1 initial hardware build.
You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel   (a)
You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (b)	You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (c)

Video 2, just over 5 minutes long, demonstrates the use of the test software.  This video is available in low resolution (a) and high resolution (b) - the high resolution will require at least a 3.5Mbps broadband data rate to view.

Video 2 - Using the test software for the part 1 build.
You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (a)	You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (b)

4. Part 2 Set of Instructions

The set of instruction for creating the LED Count Game Part 2 are:

1. Construct the Switch circuitry board - the switch circuit board consists of a circuit board within which the six 'push-to-make' switches are embedded.  The 'Start' and 'Stop' switches (red) are located above the four column selection switches (black).  Wires from the six switches, and the ground connection wire, are connected to the input ports of one of the PiFace Digital boards (board 0 - the lowest board on the PiRack).  The switches could be connected to any of the input ports on any of the PiFace Digital boards but for simplicity they have all been connected to one PiFace Digital (More Detail);
2. Download and run the switch configuration test software - download the switch test software file 'switchconfigtestv1p0p0.py', written in Python 3, and confirm that the switch board is working correctly (More Detail);
3. Download and run the game software itself (see Playing the Game).

A video, just over 4.5 minutes long, demonstrating how the switch board is built and tested is shown in Video 3.  This video is available in low resolution (a) and high resolution (b) - the high resolution will require at least a 3.5Mbps broadband data rate to view.

Video 3 - Completing the switch build and testing the switch configuration for part 2.
You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (a)	You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (b)

5. More Details

5.1 Configure the R-Pi System

The layout of the R-Pi (Model B) is shown in Figure 5.1. Once the various cables have been connected to the R-Pi, the configuration is as shown in Figure 5.2 (the alphanumeric annotations refer to the identifier entries in Tables 2.1 and 2.2).

Figure 5.1 - R-Pi Model B board layout.	Figure 5.2 - The R-Pi with the set of connected cables.

Once the various cables have been connected to the R-Pi, the configuration is as shown in Figure 5.2 (the alphanumeric annotations refer to the identifier entries in Tables 2.1 and 2.2).  The next step is to ensure that the R-Pi has the required configuration and software to support the PiFace Digital boards - see Appendix C1.

5.2 Configure the PiRack Board

The layout of the PiRack is shown in Figure 5.3.  For this project the PiRack will be used to connect the four PiFace Digital boards and so the R-Pi PiRack has four male GPIO connectors.

Figure 5.3 - PiRack board layout.

The only configuration required is for the two set of Jumpers i.e. those that define the power supply source (set to external power supply) and those that define the SPI settings (set to default). A detail explanation of what these jumpers must be set to is given in Appendix B.  Remember that an external power supply must be used and connected using the barrel jack connector.

5.3 Configure the PiFace Boards

The layout of the PiFace Digital board is shown in Figure 5.4.  In this project we will make use of the Output Ports for ALL of the PiFace Digital boards, and the Input Ports and In/Out Power Port on one of the PiFace Digital boards (an alternative design could make use of these ports on more than one PiFace Digital board).

Figure 5.4 - The layout of the PiFace Digital board.

A more detailed view of the four side aspects of a PiFace Digital board is shown in Figure 5.5.  Three features of particular relevance are:

1. The Onboard LEDs (Figures 5.5c and 5.5d) - these can be used to confirm that the software is working correctly even when there are no externally connected LEDs;
2. The Onboard Switches (Figures 5.5a and 5.5d) - these can be used to confirm that the software is working correctly, partially, even when there are no external connections to the input ports (note that the onboard switches are linked to the Input Ports 0-3 respectively);
3. The GPIO connector (Figure 5.5b) - this is the connector that is used to connect the PiFace Digital board to the PiRack.
   

The jumper settings for the PiFace Digital boards are described in Appendix A. It is ESSENTIAL that each PiFace Digital board has a unique value for the J1/J2 jumpers (see Figure 5.5b for the setting to '11').

5.4 Building the LED Electronics

The LED board is a 4x8 matrix of coloured LEDs i.e. four columns of 8 LEDs.  The LED board needs to be raised vertically so that it can be easily seen by the game player - see Figure 5.6a.  The 32 LEDs need to be fixed to the display board and the corresponding wiring soldered to the LEDs.  The soldering of the wires to the LEDs should be on the back of the LED board so that it is hidden from the game player - see Figure 5.6b.

The detailed wiring, its design and realisation, is shown in Figure 5.7.  The voltage to drive the LEDs for each column is obtained from the power port on the coresponding PiFace Digital board - see Figure 5.7a (the 5V port on the Output interface of the PiFace Dgital cannot be used as it is not possible to get a current from this port).  As shown in Figure 5.7a, each LED is connected to one of the output ports on the PiFace Digital i.e. ports 0-7 drive the 8 LEDs for a column.  The LEDs have a forward voltage of approximately 2.2V.  This means that a drop-down resistor is required to reduce the 5V source to just 2.2V across the LEDs.  This requires the use of a 180ohm resistor (see Appendix D for how this value is determined and how this value must be adjusted if the characterisitics of the LED change from those specified in the bill of materials).

It should be noted that when measured, the voltage from 5V In/Out port was 5.3V.  This would imply that a larger resistor value is requred to drop the voltage level that the 2.2V required across the LEDs.

It is the long pins on the LEDs, the anode, that are connected to the resistors and so to the 5V source port of the PiFace Digital (the red wire in Figure 5.7b).  In Figure 5.7b all of the LEDs for one column are connected to one resistor (hence 4 resistors are used).  The better approach is to use one resistor per LED and so avoid variation in the light from the LEDs when more than one is switched on.  This would mean each LED anode would be connected to its own resistor with all of the resistors connected to the 5V power source.  The wires for the connection to the PiFace Digital (the black wires in Figure 5.7b) are soldered to the cathode pin on the LED.  Once all of the wires have been soldered to the LEDs, it is essential that they are individually labelled to make it clear which wire is connected to which LED - the software that drives the LEDs identifies the LED by the board and port numbers.  It is useful to bind together the set of wires for each column using a piece of tape.

5.5 Connecting It All Together

Once the various components have been prepared, the full hardware can be constructed.  The first step should be to connect the wires from the LED board to the Output Ports and the 5V In/Out Ports on the PiFace Digital boards (see Figures 5.10a and 5.10b). Doing this before the PiFace Digital boards are connected to the PiRack and R-Pi boards avoids damaging the GPIO connectors.  Figures 5.8 and 5.9 show the PiFace Digital, PiRack and R-Pi build at different stages.  Again it is best if all of the PiFace Digital boards are connected to the PiRack before the PiRack is connected to the R-Pi.

Figure 5.8 - PiFace Digital mounted on the PiRack.

Note that in Figures 5.10a and 5.10b the red wire is NOT connected to the Output Port of a PiFace Digital board.  Instead, it is connected to the 5V In/Out port that is next to the two Output Relays.

Figure 5.11 - Fully wired and mounted set of PiFace Digital boards to LEDs.

The fully wired Part 1 system is shown in Figure 5.11.  Note that when the fully populated PiRack is connected to the R-Pi, then the weight of the set ofwires will cause the PiRack to lean and so place stress of the PiRack/R-Pi GPIO connector.  To avoid damage the PiRack should be either independently supported or the wiring arranged/supported so that is does not cause stress on the GPIO connector.

5.6 Building the Switch Electronics

The electronic design for the switches is shown in Figure 5.12.  The switches are to be connected to the input ports of one of the PiFace Digitial boards. As shown in Figure 5.12 the six switches are connected to ports 0-5.  The 'GND' port on the PiFace Digital is use to supply the ground voltage for the switches.

Figure 5.12 - Wiring of the switches to the PiFace Digital board.

Figures 5.13a and 5.13b show the front and back of the switch board to be created.  The 'Start' and 'Stop' (red) switches are on the top and the four column select switches (black) are below. All of the switches must be connected to the 'GND' port of the PiFace Digital: this is the red wiring shown in Figure 5.13b.  The wiring for the connections to the PiFace Digital input ports 0-5 is shown in yellow (these should be clearly labelled, near the end to be inserted into the PiFace Digital, so that the correct wiring order is maintained).  The four outer screws are used to support the weight of the switch board and to avoid damaging the underside of the switches and the wiring.  All of the wires are soldered to the appropriate switch connections.

The finished wiring is shown in Figures 5.14a (back) and 5.14b (side).  In Figure 5.14a the red wire is connected to the 'GND' port on the lowest PiFace Digital (as per Figure 5.12) and the yellow wires are connected to the PiFace Digital input ports 0-5 (this requires the use of a small thread screw driver).  The switch board is now located in front of the LEDs so that a game player can easily see the set of LEDs and press the appropriate switch.

If you want to connect the switches in a different order, or to a different PiFace Digitail board, or use more than one PiFace Digfital board, then the switch test and game software will have to be changed. The software is designed to monitor specific input ports/boards and so you must ensure the software monitors the ports/boards as per the wiring.

6. Playing the Game

The game software is started by running the Python 3 file 'ledcountgamev1p0p0.py'.  When the game starts the window shown in Figure 6.1 is displayed.  The game is based upon two roles: the game administrator and the game player (they may be the same person).  The game administrator is responsible for configuring the game and the game player plays the game.  The basic sequence to start a game is:

1. The game adminstrator defines the number of LED configurations to be displayed and the period for which each configuration is displayed i.e. the time in which the game player has to make a choice before a 'timeout' is declared;
2. The 'SETUP GAME' button is now pressed by the administrator so that the input values are confirmed;
3. If the input vaues are correct, the game administrator presses the 'START GAME' button (in Figure 6.2 a configuration of 10 sequence with period of 1 second, 1000ms, has been entered).  The LEDs on the LED board now flash, continually, to inform the game player that the game is ready to be played;
4. When ready, the game player presses the 'Start' switch on the switch board. The LEDs flashing stops and a count down on the LED board is completed i.e. all LED columns, 3 columns, etc.
5. The random sequence of LED displays starts and the player is expected to press one of the switches 1-4;
6. There is a 1 second delay between the display of each LED configuration (to avoid the column selection being confused when short period sequences are to be displayed);
7. Once the complete sequence has been displayed, the game reports an analysis of the game player's responses - see Figure 6.2.  This report states if the game player's response was correct, or if a timeut occurred i.e. the game player was too slow or did not press a switch, and the time taken to make the response.  A summary is reported in the bottom left area of the display;
8. The game administrator can start a new game sequence by pressing the 'SETUP GAME' button and entering the new configuration values;
9. The game player can stop the game at any time by pressing the 'Stop' switch on the switch board.  A report up to that point is then produced and displayed.
   

Figure 6.1 - The startup display for the game administrator.	Figure 6.2 - The display to a game administrator once a game activity has ended.

A video, 2.5 minutes long, demonstrating the use of the game software is shown in Video 4.  This video is available in low resolution (a) and high resolution (b) - the high resolution will require at least a 3.5Mbps broadband data rate to view.

Video 4 - Playing the game.
You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (a)	You don't have permission to edit metadata of this video. Edit media Dimensions x Small Medium Large Custom Subject (required) Brief Description Tags (separated by comma) Video visibility in search results Visible Hidden Parent content LED Count Game Instructions Poster Upload Preview Ok Cancel (b)

7. Trouble Shooting

8. Further Development Ideas

This project can be developed in a number of ways. Some ideas for you to think about, and work on, are:

• Increase the number of LED columns - if another PiRack is used, the number of supported PiFace Digital boards can be increased from 4 to 7 and so seven columns of LEDs can now be supported.  The second PiRack is connected to the top-most GPIO connector on the first PiRack board.  The LED control software has to be extended to drive the increased set of columns;
• Support more than one player - the input switches on just one PiFace Digital are used. With the current structure, up to four players could be supported in competition with each other. This will need more switch boards to be created and integrated, and the game software to be amended to support multiple players and to provide the comparison reports;
• Provide access to the game administration via a browser - the R-Pi Raspbian software includes a web server.  The game administration software could be re-written to be use browser access (the removes the need for the game administrator to have direct access to the R-Pi and its I/O devices).  This requires the GUI to be replaced by a web form and the back-end server implementation to provide the interactions/control with the PiFace Digital boards.

Appendix A - PiFace Digital Board Jumpers

The PiFace Digital has seven jumpers (see Figure A1) to define the operational configuration (see Table A1).

Table A1 - PiFace Digital jumpers.

The location of the jumpers on the PiFace Digital is shown in Figure A1.

Figure A1 - The jumpers on the PiFace Digital board.

Note that the jumpers settings shown in Figure A1 do NOT reflect the requirements for this project.

Appendix B - PiRack Board Jumpers

The PiRack has 12 jumpers that are used to define the operation configuration (see Table B1).

Table B1 - PiRack jumpers.

The jumper settings for the PiRack board are shown in Figures B1 and B2.

Figure B1 - The PiRack jumper settings for use of an external power supply.	Figure B2 - The PiRack jumper settings in the default SPI CE mode.

Note

When shipped the PiRack has the set of Jumpers J1/J2, J3/J4, J5/J6 and J7/J8 set as either Default SPI CE or Swapped SPI CE Lines. The documentation accompanying the PiRack states that the SPI CE lines do not need swapping i.e. implying that they are set as Default SPI CE.  If that was the case then the associated initialisation call in any Python code that is expected to drive the PiFace would have the line 'pfio.init()' - assuming the corresponding import assigns the module to the object identifier 'pfio'. Unfortunately, the PiRack appears to be shipped with the J1/J2 etc. jumpers configured as Swapped SPI CE Lines.  Hence the resulting 'pfio.init()' call results in the report of NO PiFace being detected.  This can be resolved in one of two ways:

1) Swap ALL the J1/J2, J3/J4, J5/J6 and J7/J8 jumper settings on the PiRack back to Default SPI CE - this is the recommended approach;

OR

2) Change the 'pfio.init()' call to 'pfio.init(True,0,1)'.  The 'pfio.init()' call is the same as writing 'pfio.init(True,0,0)'.  The first parameter (default=True) sets the initialisation of all boards to 'True', the second parameter is the SPI bus and the third is the chip_select value. It is the chip_select value that must be consistent with the J1/J2, etc. jumper settings.

The documentation concerning the init() and other PiFace API calls is supplied in the 'pifacedigital.py' module. When the PiFace is connected directly to the R-Pi i.e. without the use of a PiRack, then the Python code must use the call 'pfio.init()' otherwise the PiFace will not be detected. If only one PiFace is linked to the PiRack, then, as long as the PiRack jumpers are set correctly AND the jumpers J1/J2 on the PiFace are set to identify the PiFace card as '0', the the PiFace will be correctly identified and driven if you use the original code libraries.

Appendix C - The Software

All of the software written for this project is available in the Element14 GitHub at: https://github.com/element14/pi_project/tree/033cf73f89b60c569711186c6ae82169e065d86a/LED_Count_Game.  A clone of this software should be established using an appropriate software versioning application.  The clone can be established at: https://github.com/element14/pi_project/tree/033cf73f89b60c569711186c6ae82169e065d86a.  The four pieces of software created as part of this project are:

• LED Test Software - ledconfigtestv1p*.py;
• LED Chooser Software - ledchooserv1p*.py;
• Switch Test Software - switchtestv1p*.py;
• LED Game Software - ledcountgamev1p*.py.
  

C1 System Software

The two system configuration activities are enabing the SPI driver and installing the PiFace Digital libraries: these libraries are used to enable a Python 3 program to interact with the PiFace Digital boards.

C1.1 Enable the SPI Driver

To enable the SPI driver the file raspi-blacklist.conf file has to be edited and the line 'blacklist spi-bcm2708' must be 'commented out'.  Once edited the line should read as (the hash makes the line a comment):

     #blacklist spi-bcm2708

The file raspi-blacklist.conf can be edited by typing into the terminal interface:

     sudo nano /etc/modprobe.d/raspi-blacklist.conf

If you use the alternative technique of typing into the terminal the instruction:

     sudo modprobe spi-bcm2708

then you will have to do this every time the R-Pi is restarted.

C1.2 Install the PiFace Digital Libraries

To install the PiFace Digital libararies the R-Pi must be connected to the Intermet.  To download the initial set of libraries and to ensure that all of the relevant context settings are configured appropriately, type into the terminal the instructions:

     sudo apt-get update

     wget -O - http://pi.cs.man.ac.uk/download/install.txt | bash

Once the software installation has completed (note this will take many minutes, about 10, if you have a slow broadband link and a slow SD card) you need to restart the R-Pi:

     sudo reboot

The bad news is that this downloads a set of libraries that do not support the use of multiple PiFace Digital boards. These libraries must now be updated. The PiFace Digital Core and Common libraries need to be downloaded.  These are available at (make sure you download the PYTHON 3 versions i.e. the download buttons on the right hand-side):

• Latest PiFace Common software (v3.1.1) - download from GitHub at https://github.com/piface/pifacecommon/releases
• Latest PiFace Digitalio software (v2.1.0) - download from Github at https://github.com/piface/pifacedigitalio/releases

NOTE: Do not use any releases other than those above as problems with the software and later releases of these libraries have been detected.  We are working through these problems and will update the documentation and source code once resolved.

This software is then installed using the instruction:

     sudo dpkg -i python3-piface*.deb

Note that at present the usual upgrade instructions, following,  do not work as these new releases are not yet being maintained by the Raspbian packagers.

     sudo apt-get update && sudo apt-get upgrade

     sudo apt-get install python3-pifacedigitalio

C2 LED Test Software

C2.1 Using the Software

The LED configuration test software is a prescripted sequence of tests applied to the external LEDs.  The software is started by running the file 'ledconfigtestv1p0p0.py'.  This simple Python3 program is used to check that the basic LED configuration (hardware and software) is correct for the 4 set of PiFace boards linked to the R-Pi using a PiRack. Even if there are no external LEDs the PiFace onboard LEDs should change state as required.  When watching the external and onboard LEDs the following should be observed:

1. All LEDs should be off;
2. The individual LEDs connected to PiFace Digital board 0 will switch on, and then off;
3. As per the 2) above repeated for PiFace Digital boards 1, 2 and 3 in sequence;
4. All LEDs are now off;
5. All LEDs on PiFace Digital board 0 are switched on together for 3 secs and then switched off;
6. As per 5) above repeated for PiFace Digital boards 1, 2, and 3 in sequence;
7. All LEDs should be off;
8. All LEDs on ALL PiFace Digital boards are switched on together for 5 sec and then switched off;
9. All LEDs should be off.

As the state of the LEDs is changed, there is a on-screen report that states what should be observed during that phase of the test cycle. At the end of the tests all of the LEDs should be switched off.

C2.2 The Software Design

The software does not contain any classes.  There is a single sequence of instructions. The first key feature are the lines that include and initialise the PiFace Digital cards.

import pifacedigitalio as pfio

from time import sleep

pfio.init(True,0,0)

The 'import' statement establishes the dependence and use of the PiFace Digital I/O libraries and assigns these to the object instance 'pfio'.  The object is initialised using the init() call (see Appendix B for values of the parameters.  The next key feature is the code used to turn a LED on/off:

pfio.digital_write (CLED1, CLEDON, CBOARD1)

This line states that LED 0 (identified using the constant CLED1), on PiFace Digital board 0 (identified using the constant CBOARD1), should be set as on (using the constant CLEDON).  To turn the same LED off the statement is:

pfio.digital_write (CLED1, CLEDOFF, CBOARD1)

The set of constants, these are identified as uppercase variables starting with a 'C', are defined at the head of the file, after the file header comments.

C3 LED Selection Software

C3.1 Using the Software

The LED selection software provides the user with the ability to control the state of all and any of the LEDs.  The software is started by running the file 'ledchooserv1p0p0.py'. When it runs, the window shown in Figure C1a is displayed.  This is a schematic representation of the LED board i.e. the set of red LEDs that are connected to PiFace Digital boards 1 and 4, etc.

Figure C1a - The display presented to the tester.	Figure C1b - The LED chooser software in use.

As shown in Figure C1a, the user is presented with three configuration options:

• All LEDs On - when pressed ALL of the LEDs on the LED board are switched ON;
• All LEDs Off - when pressed ALL of the LEDs are switched OFF;
• Use Checklist - when pressed the selection made using the set of check boxes are now displayed.  An example is shown in Figure C1b

The text box at the foot of the window provides a text description of the state of the LEDs.  The content of this box reflects, in real-time, the selection of the buttons and the check boxes.

C3.2 The Software Design

The software contains one class (Application).  The first key feature are the lines that include and initialise the PiFace Digital cards.

import pifacedigitalio as pfio

from time import sleep

from tkinter import *

The first 'import' statement establishes the dependence and use of the PiFace Digital I/O libraries and assigns these to the object instance 'pfio'.  The second 'import' statement imports the the GUI libraries from 'tkinter'.  The main program instructions are:

root = Tk ()                               # Create the GUI root object

root.title ("LED Chooser")       # Give the application window a title

app = Application (root)           # Create the root application window

root.mainloop ()                        # Establish the operation loop

The design of the Application class is shown in Figure C2.

Figure C2 - The structure of the Application class in the LED chooser software.

This class has no attributes and five methods.  The functionality of the five methods are:

• __init__ () - defines all the initialisation states for the GUI (this function is called when the 'app' object is instantiated using the statement app = Application (root));
• create_widget () - creates the set of buttons, checkboxes and the text area as shown in Figure C1a.  Defines the actions to be invoked when the state of the GUI is changed;
• turnall_on () - turns all of the LEDs on.  This method is invoked when the 'All LEDs ON' button is pressed;
• turnall_off () - turns all of the LEDs off.  This method is invoked when the 'All LEDs OFF' button is pressed;
• update_text () - updates the text area with the individual status of the LEDs (as shown in Figure C1b).

C4 Switch Test Software

C4.1 Using the Software

The Switch test software is a prescripted sequence of tests applied to the external and onboard switches.  The software is started by running the file 'switchconfigtestv1p0p0.py'.  This simple Python3 program is used to check that the external and onboard (to the PiFace Digital boards) swiches are correctly wired. The sequence of tests is:

1. A request will be made to press each of the onboard switches (for all of the connected PiFace Digital boards);
2. A request will be made to press each of the external switches (for just one PiFace Digital board and for the six switches that are wired to that board).

If you do not press the switch OR the PiFace Digital board is not present then the test will proceed to the next switch.  One of three reports will be printed:

1. The button was pressed;
2. A timeout occurred;
3. No PiFace Digital Board is not present.

As the state of the Switches is changed, there is a on-screen report that states what actions should be undertaken in that phase of the test cycle and the detected results of that action.

C4.2 The Software Design

The software does not contain any classes.  There is a single sequence of instructions. The first key feature are the lines that include and initialise the PiFace Digital cards.

import pifacedigitalio as pfio

from time import sleep

pfio.init(True,0,0)

The 'import' statement establishes the dependence and use of the PiFace Digital I/O libraries and assigns these to the object instance 'pfio'.  The object is initialised using the init() call (see Appendix B for values of the parameters.  The other key feature of the software is the code that is used to detect input from a switch:

count = 0

input_value = pfio.digital_read (CSWITCHSTART, CSWITCHBOARDSTART)

if input_value == False:

    while input_value == False and count < CMAXCOUNT:

        input_value = pfio.digital_read (CSWITCHSTART, CSWITCHBOARDSTART)

        count = count + 1

    if count == 0:

        print ("No PiFace Digital Board")

    elif count < CMAXCOUNT:

        print ("Start Button Pressed")

    else:

        print ("*** TIMEOUT")

This code is controlling the detection of the state of the 'Start' switch (identified using the constant 'CSWITCHSTART') on the PiFaceDigital board identified using the constant 'CSWITCHBOARDSTART'.  The code monitors the state of the switch using the pfio.digital_read() functions.  The counter, count, is used to provide a timeout period after which the software will carry on to the next test.  If a timeout appears, i.e. the switch is not pressed within the defined period (the value of the constant 'CMAXCOUNT'), then a corresponding report is made. This code also detects whether or not a PiFace Digital board is present and makes an appropriate report.

The set of constants, these are identified as uppercase variables starting with a 'C', are defined at the head of the file, after the file header comments.

C5 Game Software

C5.1 Using the Software

The Game Software controls the LED counting game play.  The software is started by running the file 'ledcountgamev1p0p0.py'.  An explanation of how to use the game software is available in Section 6 - "Playing the Game".

C5.2 The Software Design

The software contains one class (Application).  The first key feature are the lines that include and initialise the PiFace Digital cards.

import pifacedigitalio as pfio

from time import sleep

from tkinter import *

import random

The first 'import' statement establishes the dependence and use of the PiFace Digital I/O libraries and assigns these to the object instance 'pfio'.  The second 'import' statement imports the the GUI libraries from 'tkinter'.  The main program instructions are:

root = Tk ()                                            # Create the GUI root object

root.title ("LED Counting Game")        # Give the application window a title

app = Application (root)                       # Create the root application window

root.mainloop ()                                    # Establish the operation loop

The design of the Application class is shown in Figure C3.

Figure C3 - The structure of the Application class in the game playing software.

This class has no attributes and eleven methods.  The functionality of the eleven methods are:

• __init__ () - defines all the initialisation states for the GUI (this function is called when the 'app' object is instantiated using the statement app = Application (root));
• create_widget () - creates the set of instructions, buttons and the text area as shown in Figure 6.1.  Defines the actions to be invoked when the state of the GUI is changed;
• start_game () - starts the game by initialising the game as configured as starts the LED quadrant display sequence. This method is invoked when the game administrator presses the 'Start Game' button on the GUI;
• choose_game_setup () - validates the inputs provided by the player (the next step is to press the 'Start Game' button). This method is invoked when the game administrator presses the 'Setup Game' button on the GUI;
  
• stop_game () - This method is invoked when the game player presses the 'Stop' button on the switch panel;
  
• turnall_off () - turns all of the LEDs off;
• quadrant_on_off () - this is the method that controls the quadrant display of the LEDs i.e. LEDs are switched on/off in a four quadrant cycle. This cycle is displayed while the game waits for the game player to press the 'Start' switch on the switch board;
• process_config () - controls the playing of the game by displaying each of the configurations and then producing the associated results tables;
• generate_random_LEDs () - responsible for generating the set of LEDs that are displayed for each of the four columns. This ensures that no two columns display the same number of LEDs;
• calculate_statistics () - this works out the player statistics at the end of the game and puts these into the statistics panel;
• calculate_results () - this places the player's results in the results panel.

Appendix D - Basic Electronics Primer

D1 Resistors

The value for a resistor is marked on the resistor itself using a set of coloured bands.  This band coding is shown in Figure D1. It should be noted that the final band, the tolerance, is always clearly separated from the other bands to provide the orientation of the band sequence i.e. make sure the tolerance band is on the far right.

Figure D1 - The colour band code for resistor values.

A resistor is used to drop the voltage i.e. to dissipate energy (this is why a resistor can get hot when in use).  The relationship between the current through a resistor, the voltage across the resistor and the resistance is given by Ohm's Law:

     Current through the Resistor (I_r) = Voltage across the Resistor (V_r) / Resistance (R)      i.e.     I_r  =  V_r / R     or       I_r R = V_r

The energy that can be disspated by a resistor is calculated as:

     Power dissipation (Watts) = Current through the Resistor (I_r) * Voltage across the Resistor (V_r)      =      I_rV_r      or      I_r²R

This value must be less than that specified for the resistor otherwise the resistor will melt.

D2 LEDs

If the LED is connected to a power supply that exceeds the forward voltage of the LED, then a drop-down resistor must be used.  The value of this resistor is calculated as shown in Figure D2.

Figure D2 - Drop-down resistor for use with an LED.	Figure D3 - The circuit diagram for the full set of LEDs connected to a PiFace Digital

In Figure D2 the LED is defined in termes of its Forward Voltage (V_f) and Forward Current (I_f).  The value of V_s is that supplied from the PiFace Digital In/Out Port. In this project the value of the resistor is detemined for an LED when I_f = 20mA, V_f = 2.2V and V_s = 5.3V, then R = (5.3 - 2.2)/20*10³ then R = 155ohm.  For this project a value of 180ohm was selected because the LEDs used varied in forward voltage and current.  If an LED is too dim when lit by itself, then decrease the resistor value.  The circuit diagram for the full set of LEDs connected to a PiFace Digital is shown in Figure D3 i.e. when there is a drop-down resistor for each LED.

D3 Wiring the LEDs

As shown in subsection D1, the power dissipated across the resistor is I_rV_r Watts (W).  Assuming a single resistor per LED then I_r = 20mA and V_r = (5.3-2.2)V and so the power dissipated is 62mW (well under the 2W maximum for these resistors).  When each LED draws 20mA then the total current drawn on a PiFace Digital is 160mA (8 * 20mA) and so the total current drawn on the PiRack is 640mA (4 * 160mA).

Terminology

About this Document