Hardware Control Systems

1 Introduction

Starting in the early 2000's, pinball control systems have been released. These systems enable users (and manufacturers) to modify existing games or create new machines. Custom machines based on these control systems are featured at most pinball shows and conventions, and new pinball companies are using them commercially to run their games.

Manufacturers of control systems include:

• Multimorphic, producing the P-ROC and P3-ROC systems
• FAST Pinball
• Ben Heck, who has developed the Pinheck board which is used by Spooky Pinball LLC in America's Most Haunted
• milliSoft, who offers an all-in-one board

2 P-ROC/P3-ROC

Official Website

The P-ROC / P3-ROC (and their related driver boards) are a set of pinball machine controller boards that allow a computer running custom software to control a pinball machine. The P-ROC board is an intelligent interface board that controls the low level pinball machine circuitry according to instructions from the computer running the game code.

In most cases, a single-board computer works quite well as the computer. The P-ROC board can be used to either (1) replace the CPU board on existing machines (WPC-x, Stern Whitestar, or Stern S.A.M. systems) so they can run custom software, or (2) control a new pinball machine, whereas a P3-ROC can be used only to control new machines.

P-ROC / P3-ROC Feature Support
	WPC Driver Boards	Stern Driver Boards	PDB (P-ROC Driver Boards)	Switch Matrix	Serial Switch Boards	DMD Support	Aux Port	I2C	GPIOs
P-ROC	Y	Y	Y	Y	N	Y	Y (WPC compatible)	N	N
P3-ROC	N	N	Y	N	Y	N	Y (Custom)	Y	Y

2.1 Functionality

A P-ROC combined with a PC or embedded microcontroller provides functionality equivalent to a CPU board in a pinball machine. Software runs on the PC or microcontroller and communicates with the pinball machine's features through the P-ROC via USB.

The P-ROC is essentially an FPGA (Field Programmable Gate Array) surrounded by some support logic and a bunch of connectors. The FPGA contains custom logic enabling it to perform tasks including:

• Communicating with a PC over USB
• Scanning switches for switch events (Direct, Matrixed, and Burst)
• Driving coils, lamps, motors, etc (Direct and Multiplexed)
• Driving a Dot Matrix Display (DMD)

Note that the P-ROC does not handle audio. Instead audio is typically processed by the computer or microcontroller which is running the game software connected to the P-ROC.

The support logic and connectors enable the P-ROC to be used as a controller in custom homebrew pinball machines or as a CPU board replacement in the following generations of machines:

• WPC
• WPC-95
• Stern Whitestar
• Stern S.A.M.

2.1.1 USB Control

The power of a personal computer can be leveraged to create pinball machine software with simple or complex rulesets, video sequences, and audio effects. The PC's audio output can be connected directly to a pinball machine, but interfacing to the machine's switch and driver circuits and to display elements such as a dot matrix display requires an interface card such as a P-ROC.

2.1.1.1 Hardware Implementation

The P-ROC has a type B USB connector allowing it to connect directly to a PC using a standard USB cable. The USB signalling protocol is handled by an FTDI FT245RL chip on the P-ROC. This chip buffers incoming data destined for the FPGA and outgoing data being sent back to the PC. For more information about the FT245RL chip, refer to its datasheet.

2.1.1.2 USB Drivers

FTDI provides a free, closed-source driver for the FT245RL chip called D2XX. P-ROCs have been verified to work successfully with Windows based systems using D2XX. Attempts to communicate with a P-ROC in Mac OS using D2XX have been unsuccessful due to an apparent bug in the Mac OS D2XX implementation.

A free, open-source driver called libFTDI is also available. P-ROCs have been verified to work successfully in Linux and Mac based systems using libFTDi.

2.1.1.3 USB Bandwidth

The P-ROC can send/receive approximately 1 MB of data each second, which is more than enough to exchange any information needed to control a pinball machine, including DMD animation information at frame rates exceeding 60 fps.

2.1.2 Switch Control

The P-ROC can automatically scan direct, matrix, and burst switches and notify software and/or change the state of a driver when a switch changes states. This allows software to spend its cycles processing game rules rather than implementing very high speed switch scan loops.

2.1.2.1 Direct and Matrix Switches

The P-ROC has 32 direct switch inputs, and it has 10 switch column drivers and 16 switch row inputs creating a 160 switch switch matrix. The first 8 switch column drivers have dedicated outputs driven through a ULN2803 transistor array, and the other 2 are driven on an 8-bit multiplexed data bus (for WPC machines to use 8-driver boards). The 16 switch row inputs are dedicated inputs, each going through an LM339 comparator that compares the row's voltage against a 2.5V or 6V reference voltage.

Every x milliseconds, the P-ROC goes through a scanning loop during which it first checks all of the direct inputs. It then iterates through the matrix by driving a column and checking the row inputs, then driving the next column and checking the row inputs, etc. The number of milliseconds between each full scanning loop is programmable down to 1 millisecond.

2.1.2.2 Burst Switches

The P-ROC has 32 burst switch outputs (each with two outputs) and 64 burst switch inputs. These are provided for switches, such as long range infrared emitter/detector pairs, that require bursts of activity to function correctly. The timing parameters of the burst activity are fully programmable (globally) so that it can work with many types of switches. The programmable timing parameters determine how long it takes to cycle through all of the burst switches.

2.1.2.3 Switch Events

While scanning the switches, the P-ROC recognizes when the state of a switch changes. States include:

• Open, non-debounced
• Open, debounced
• Closed, non-debounced
• Closed, debounced

The P-ROC can be programmed to perform specific actions for each state change for each of the 256 switches. Actions include:

• Notify software
• Change a driver's configuration

For increased flexibility, the P-ROC can chain multiple actions together so that more than one action can occur as a result of a switch's state changing. For instance, switch 3 can cause drivers 5, 10, and 20 to turn on, drivers 30-35 to be turned off, and software to be notified when its state becomes closed, debounced. (Crazy example, but possible). It can also have a different set of actions occur when its state becomes one of the other 3 states, such as open, debounced.

In typical applications, users will likely want to simply notify the host of all debounced switch events (for scoring and rule processing). For situations requiring immediate driver reactions, such as pop bumpers popping in response to a pop bumper switch closing, a driver rule might also be used.

2.1.3 Driver Control

The P-ROC can individually control 216 driver outputs. Driver outputs are typically used to control coils, lamps/leds, motors, etc. There are dedicated output pins for 32 of the 216, and the other 184 are driven through a multiplexed bus that is compatible with WPC, WPC95, Stern Whitestar, and Stern S.A.M. power driver boards.

2.1.3.1 Multiplexed Bus

The Multiplexed Bus contains:

• 8 data bits
• 9 enable bits

The functionality of the data and enable bits is controlled by a large set of configuration registers. For detailed information about the registers, refer to the P-ROC FPGA Specifications on the P-ROC Documentation Page.

2.1.3.2 Timing

Every millisecond, the P-ROC checks to see if the internally programmed state of a driver has changed (either by a software write or by a switch event action). When the internally programmed state of a driver with a dedicated output pin changes, the new state is reflected immediately on the pin. Circuits connected to the multiplexed bus won't see driver changes immediately. Rather, they will see the change whenever the bus logic services the changed driver. How long that can take is determined by the configuration registers.

2.1.3.3 Driver Modes

The P-ROC can automatically control drivers in certain modes so that software doesn't need to programmatically turn on/off things like blinking lights or repeatedly pulsing coils. The following modes can be used:

2.1.3.3.1 Solid

This is the simplest mode. Drivers in this mode are either on or off, and they remain in that state until reconfigured.

Note - Drivers connected to high current coil circuits should NEVER be turned on solidly. They should be driven with a timer (see the timed mode below).

2.1.3.3.2 Timed

A timed driver is turned on for a specified number of milliseconds, up to 255. When the millisecond timer expires, the driver is turned off.

This mode is recommended for high current coil circuits that need to be pulsed for short periods of time.

2.1.3.3.3 Schedule

A scheduled driver turns on or off automatically according to a 1 second schedule. The schedule contains 32 timeslots, each lasting for 31 microseconds. When the timer enters an active timeslot, the driver turns on. When the timer enters an inactive timeslot, the driver turns off.

Note - The timed mode can also be used for scheduled drivers. When a schedule driver is configured with a timer, the timer determines how many seconds the schedule is repeated.

Scheduled drivers are recommended for blinking lamps/flashers. Various light effects can be created by assigning different schedules to a set of lamp drivers.

2.1.3.3.4 Patter

Patter (named after the phrase pitter-patter) drivers repeatedly turn on for a certain number of milliseconds and then off for a certain number of milliseconds.

Note - The timed mode can also be used for patter drivers. When a patter driver is configured with a timer, the driver turns on for the number of milliseconds specified by the timer. When the timer expires, the patter begins and repeats indefinitely.

This mode is provided for fine-grained control of pulsed coils, such as Stern flipper coils that don't have hold circuits. An example configuration would be to combine the Timed and Patter modes to pulse the coil and then patter it when the flipper button is pressed. The driver could then be turned off when the flipper button is released.

2.1.4 DMD Control

The P-ROC is capable of directly driving a Dot Matrix Display (DMD) through a 14-bit ribbon cable. Supported DMD features include:

• Programmable resolution, including 128x32.
• Up to 16 brightness levels (colors)
• 48 kb frame buffer storage (3 full frames @ 128x32)
• Frame events (for software synchronization)

Note: The P-ROC does not supply the electrical power for the DMD. The DMD must be powered by other circuits/supplies. If you're using the P-ROC to replace the CPU board in an existing machine, then all you need to do is hook up the 14-pin ribbon cable since the existing DMD gets its power from the existing machine's power supply. If you're building a new machine, you'll need to power the DMD from your power supply in addition to making the 14-pin ribbon connection to your P-ROC.

2.2 Getting Started

2.2.1 Hardware Installation

2.2.1.1 Hardware Mounting

The P-ROC should be mounted into a pinball machine so that the board doesn't flex much when cables are attached or removed. P-ROC mounting plates are available for existing machines including: WPC, WPC-95, Stern Whitestar, and Stern SAM. Generally, each P-ROC is sold with the customer's choice of a mounting plate. Additional plates can be purchased from pinballcontrollers.com. The mounting plates were designed to mount in the same position as each machine's existing CPU board, which needs to be removed when using a P-ROC.

When mounting a P-ROC into a custom cabinet, either make use of one of the pre-designed mounting plates, or secure the P-ROC board using all 6 mounting holes on the circuit board. Not properly mounting the board increases the chances of damaging the board when attaching or removing cables. Such damage is not covered by any warranty.

2.2.1.2 Cabling

When using a P-ROC in a custom machine, any or all of the connectors can be used. Refer to the Board Specifications on the P-ROC Documentation Page for a description of the available connectors and their functionality.

When using the P-ROC in an existing machine, only some of the connectors should be used. The P-ROC Connector Mappings document on the P-ROC Documentation Page identifies which connectors should be used in each of the 4 supported existing pinball machine platforms.

2.2.1.3 Hardware Switches

The P-ROC has 4 DIP switches of which only 3 are currently used:

• DIP switch 1 sets the polarity of the 'clear' signal used to disable driver circuits on connected power/driver boards.

OFF : 'clear' goes high (logic 1) to disable drivers. Used with WPC and WPC-95 machines. Typically also used with PDB driver boards, even though the switch position should not matter.

ON : 'clear' goes low (logic 0) to disable drivers. Used with Stern Whitestar/SAM machines.

Important: Before applying power to a machine with an installed P-ROC, ensure DIP switch 1 is set as desired:

• DIP switch 2 is used to enable USB control or embedded control.

OFF : USB control

ON : Embedded control

• DIP switch 3 determines the default operation of the DMD pins.

OFF : DMD pins carry the DMD signals.

ON : DMD pins carry output driver enables 9 through 12, as follows:

P-ROC DMD Pin mapping
DMD Signal	Output Driver Enable
rdata	9
rclk	10
latch	11
sdata	12

2.2.2 Connecting Switches

The P-ROC has a bunch of comparator circuits, similar to WPC and Stern CPU boards, to detect when your machine's switches change state. To make it easy on people who want to use their P-ROC in an existing WPC or Stern machine, the P-ROC has practically the same set of switch connectors that WPC and Stern CPU boards have. When replacing one of those boards, it's therefore a simple matter to plug all of the existing cables directly onto the P-ROC. Refer to the P-ROC Connector Mappings document for a mapping of WPC and Stern switch connectors to P-ROC switch connectors.

2.2.2.1 Dedicated and Matrixed Switches

The P-ROC has support for the following dedicated and matrixed switch configurations:

• 32 dedicated switch inputs and an 8x8 switch matrix (96 switches total)
• 24 dedicated switch inputs and an 8x16 switch matrix (152 switches total)

If you're using the P-ROC in a machine with custom wiring, you're free to connect your switch wires to any of the available switch connectors on the P-ROC. Some of the connectors are 0.100" pitch (WPC-style), and others are 0.156" (Stern-style). Refer to the P-ROC Board Specifications for a detailed list of all of the switch connectors on the board.

The dedicated and matrixed switch inputs on the P-ROC use a voltage reference that comes from the power cable you use to power the P-ROC. In a WPC machine, the power cable provides 12V to the switch logic, and the comparator reference is 6V. In a Stern machine, the power cable provides 5V to the switch logic, and the comparator reference is 2.5V. When using the 4-pin ATX power supply style power connector, it works like a WPC machine with 12V on the switch logic and a comparator reference of 6V.

2.2.2.1.1 Connecting Dedicated Switches

All of the dedicated switch inputs on the P-ROC have pull-up resistors to the switch power rail (12V or 5V as mentioned above). Therefore, when a switch input is unused, the P-ROC will pull the line up to the switch power rail.

2.2.2.1.2 Mechanical Switches

When wiring dedicated mechanical switches on your machine, make sure to wire them between the desired switch input and ground. When the switch is open, the corresponding pull-up resistor on the P-ROC will pull the line high. When the switch is closed, a connection to ground is made, and the P-ROC will see the line go low and detect the closing switch event. When the switch is opened again, the P-ROC will see the line go high and detect the opening switch event.

2.2.2.1.3 Opto Switches

Dedicated opto switches consist of an IR transmitter and a IR phototransistor (receiver). The transmitter gets connected directly to power through a current limiting resistor (resistor value depends on the power level and the specific type of IR transmitter you use) so that it always transmits. The phototransistor works similarly to a mechanical switch except reversed. The circuit is pulled high on the P-ROC when not enough light is detected by the phototransistor (ie. when a ball is blocking the light) and driven low when the light is not blocked.

2.2.2.1.4 Connecting Matrixed Switches

The P-ROC supports switch matrixes up to 8x16. When in use, the matrix functionality automatically scans the matrix, capturing switch events on each switch in the matrix as they occur.

The topology of the matrix is 8 outputs (columns) and 16 inputs (rows). Refer to the P-ROC Board Specifications for a detailed listing of the connectors to use when wiring up your matrix. To use the full 8x16 matrix, you'll need to use the 0.156" pitch connectors. If you only need an 8x8 matrix, you can use either the 0.100" or 0.156" pitch connectors.

When the P-ROC is scanning the matrix, it will drive each matrix output low, one at a time, while capturing the states on each of the inputs. By iterating through each output, it can capture the states of each and every switch on the matrix in a very short amount of time, configurable down to 1 millisecond.

All switches on your matrix need to have a 1N4004 or equivalent diode in series with the switch. It doesn't matter which side of the switch the diode is on. Just make sure to orient the diode so the bar end points towards the P-ROC matrix output.

2.2.2.1.5 Mechanical Switches

2.2.2.1.6 Opto Switches

Unlike mechanical switches, which can be used on a matrix input in the same fashion as a dedicated input (with the addition of a diode), opto switches require some more circuitry. There are a few reasons for this, but the primary reason is that opto circuits are constantly active. In other words, the IR transmitter is constantly sending light, and the phototransistor is constantly trying to detect light. This means the output of the phototransistor is always active. Therefore, if it shares a P-ROC matrix input with other switches, it will corrupt the detected states of the other switches.

This issue is resolved, as shown in the diagram below, by adding a comparator circuit that compares the output of a phototransistor to a P-ROC matrix output reference. The P-ROC matrix output reference needs to be generated by even more circuitry (not shown) so that the phototransistors output is only relevant when the P-ROC matrix output is active. In other words, when the P-ROC matrix output is active (driven low), the phototransistor's output determines whether the P-ROC matrix input is driven low or pulled high. When the P-ROC matrix output is inactive, the phototransistor's output will result in the P-ROC matrix input being pulled high, regardless of the amount of light detected.

The P-ROC matrix output reference is commonly created with another comparator circuit that compares the P-ROC matrix output to a fixed voltage that's typically some percentage of the switch power.

Instead of wiring all of these comparator circuits for each and every opto you want to use on the switch matrix, it would be much simpler to use an existing opto board. A common opto board used in many existing pinball machines for the exact same purpose is:

A-15576 : 7-Opto Switch Board

This board is available from many pinball component suppliers and contains everything you should need except the IR transmitters and phototransistors, which incidentally are also available from most suppliers on PCBs and as standalone components (transmitters, receivers).

2.2.3 Software Development

2.2.3.1 Installation/Build Instructions

Build instructions are available for:

• Windows (MinGW)
• Windows (Visual Studio)
• Linux
• Mac

2.2.3.2.1 Custom (PDB)

• Example Machine Config File (YAML) for P-ROC (sample_pdb.yaml)

sample_pdb.yaml

• Example Machine Config File (YAML) for P3-ROC (simple.yaml)

1. P-ROC Game Description file a sample machine using PDBs (PinballControllers.com Driver Boards) and Serial Switch Boards

PRGame:
    machineType: pdb
    numBalls: 4
PRFlippers:
    - flipperLwR
    - flipperLwL
PRBumpers:
    - slingl
    - slingr
PRSwitches:
    # **** Format ****
    # name:
    #   number: <number>
    #   type: <type>
    #
    #   <number> can be: x (x = 16 * Switch board addr + output number)
    #   <type> can be: 'NO' (normally open.  This is the default; so no need to use this)
    #                  'NC' (normally closed.  Common for optos)


    # flippers shown below are examples of dedicated switches
    flipperLwR:
        number: 0

    flipperLwL:
        number: 1

    # slings shown below are examples of matrix switches
    slingl:
        number: 2

    slingr:
        number: 3

# Coil numbering format: Ax-By-z:

# Capital letters are required, lower case letters represent the numbers:
# x : Board address (0-7)
# y : Bank address (0 for A, 1 for B)
# z : Output number (0-7)

PRCoils:
    flipperLwLMain: 
        number: A0-B1-0
    flipperLwLHold: 
        number: A0-B1-1
    flipperLwRMain: 
        number: A0-B1-2
    flipperLwRHold: 
        number: A0-B1-3
    slingl: 
        number: A0-B1-4
    slingr: 
        number: A0-B1-5

# Lamp numbering format: C-Ax-By-z:R-Am-Bn-p:

# Capital letters are required, lower case letters represent the numbers:
# For Columns (Source circuits - represented by the 'C')
# x : Column board address (0-7)
# y : Column bank address (0 for A, 1 for B)
# z : Output number (0-7)

# For Rows (Sink circuits - represented by the 'R')
# m : Row board address (0-7)
# n : Row bank address (0 for A, 1 for B)
# p : Output number (0-7)


PRLamps:
    testLamp:
        number: C-A1-B0-0:R-A1-B1-0
    VUK_right_b:
        number: C-A1-B0-0:R-A1-B1-1
    VUK_right_g:
        number: C-A1-B0-0:R-A1-B1-2
    VUK_left_g:
        number: C-A1-B0-0:R-A1-B1-3
    VUK_left_b:
        number: C-A1-B0-0:R-A1-B1-4
    VUK_left_r:
        number: C-A1-B0-0:R-A1-B1-5

PRDriverGlobals:
    lamp_matrix_strobe_time: 200
    use_watchdog: True
    watchdog_time: 1000

• Simple Game Script (PDB)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypePDB)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

2.2.3.2.2 WPC

• Example Machine Config File (YAML) for WPC (JD.yaml)

JD.yaml

• Simple Game Script (WPC)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypeWPC)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

• Simple Game Script (WPC95)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypeWPC95)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

• Simple Game Script (WPCAlphanumeric)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypeWPCAlphanumeric)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

2.2.3.2.3 Stern

• Example Machine Config File (YAML) for Stern Whitestar (LOTR.yaml)

LOTR.yaml

• Example Machine Config File (YAML) for Stern SAM (POTC.yaml)

POTC.yaml

• Simple Game Script (Stern Whitestar)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypeSternWhitestar)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

• Simple Game Script (Stern SAM)

import procgame.game
import pinproc 
game = procgame.game.GameController(machine_type=pinproc.MachineTypeSternSAM)
game.load_config('simple.yaml')
game.enable_flippers(enable=True)
game.lamps.testLamp.schedule(schedule=0x00ff00ff, cycle_seconds=0, now=False)
game.run_loop()

2.2.3.3 Game Development Resources

• Fonts (.dmd format)

2.4 Projects

• JD_rules - Custom JD Software
• Single Board Computers
• Pyprocgame_vp, pyprocgame, Visual Pinball
• There's a game called "Starter" which comes in the P-ROC software download package. It's not complete, but a nice starting point.
• Judge Dredd, by Gerry Stellenberg
• Cactus Canyon, by forum user Epthegeek
• The Addams Family, by forum user Compy
• Indiana Jones, The Pinball Adventure, by Jim from http://mypinballs.co.uk
• Whirlwind, by Jim from http://mypinballs.co.uk
• Creature from the Black Lagoon, by Adam Preble
• F-14 Tomcat Second Sortie, by forum user Snux
• Earthshaker Aftershock, by Scott Danesi
• The X Files, by forum user Koen
• The Mission Pinball Framework, a work-in-progress by forum users Brian Madden and Gabe Knuth (This is not a single game, but rather a game framework alternative to pyprocgame that also works with the P-ROC)

There's a discussion in the pinballcontrollers forum about which of these games you should look at first in order to understand them. The general consensus is you should start with Creature from the Black Lagoon, then dig into The Addams Family. Eric's Cactus Canyon is complete with a lot of modes and very complex (including support for color DMDs), so it's not something a newbie should jump into right away.

2.5 Additional resources

• Modifying a WPC-95 board for Audio Input
• PinballControllers.com website
• PinballControllers.com discussion forums

3 FAST

Official Website

4 Single Board Computers

A single board computer is a complete computer built on a single circuit board[1].

Some people in the P-ROC community are investigating various single board computers for use as an alternative to a full PC or laptop (as the host from which to control the P-ROC hardware).

4.1 Overview

Solution	Cost	CPU	RAM	Storage	AV	Other
Beagleboard	150 USD	600MHz	128MB	256MB Flash, SD/MMC	Audio I/O, DVI-D + S-video out	USB OTG
Chumby Hacker Baord	90 USD	454MHz	64MB	512MB uSD	Composite video out, audio I/O	3 USB
ODROID U3	75 USD	1.7GHz quad core	2GB	128MB Flash	HDMI, Audio I/O	USB host, USB OTG, Ethernet, GPIO, I2C
Raspberry Pi	40 USD	700MHz	512MB	SD Card Slot	HDMI out, Audio I/O	USB host, USB OTG, Ethernet

4.2 Beagleboard

4.2.1 Links

• beagleboard.org
• P-ROC software (libpinproc/pyprocgame) Setup Guide

4.2.2 Beagleboard Setup Guide

This setup guide outlines how to get libpinproc/pyprocgame running on a Beagleboard-xM under Ubuntu (11.04).

Note: The guide was made using a Beagleboard-xM Rev C. If anything is different with other Beagleboard versions, the difference *should* be slight.

4.2.2.1 Installing Ubuntu 11.04

The elinux.org installation guide for Natty 11.04 was followed exactly, and it worked perfectly.

4.2.2.2 Installing libpinproc

First things first, you'll probably want to create a user account instead of doing all of this as root. Starting as root:

   useradd <username>
   passwd <username>

Next edit /etc/sudoers and add the new user under the User privilege specification.

Now log out and log back in as <username>.

You'll also need to activate your ethernet port. You can do this by running "sudo dhclient eth0" every time you boot, or just add "dhclient eth0" to the /etc/rc.local file so it automatically runs at startup.

Now, for convenience, you might want to setup the ssh server so you can ssh in:

   sudo apt-get install openssh-server

If you want to continue now through an ssh connection, you can.

4.2.2.2.1 Tools / Python

   sudo apt-get install libftdi-dev git-core build-essential g++ cmake python-dev

Note - This installed python 2.7, which seems to work fine.

4.2.2.2.2.1 yaml-cpp

Download, copy to your Beagleboard (I used 'scp'), and unzip. The cd into the newly unzipped directory and run:

   mkdir bin; cd bin
   cmake ..
   make
   sudo make install

4.2.2.2.3 libpinproc

Use git to get the repository, then build with the -fPIC option:

   git clone git://github.com/preble/libpinproc.git
   cd libpinproc
   mkdir bin; cd bin
   cmake -DCMAKE_CXX_FLAGS="-fPIC" ..
   make
   sudo make install

4.2.2.3 Installing pyprocgame

4.2.2.3.1 pypinproc

To install without modifying any files, your pypinproc directory should be at the same level as libpinproc.

   git clone git://github.com/preble/pypinproc.git
   cd pypinproc
   sudo python setup.py install

4.2.2.3.2 pyprocgame

   git clone git://github.com/preble/pyprocgame.git
   cd pyprocgame
   sudo python setup.py install

Note - This should have automatically installed setuptools, which is used later in this guide. If it didn't, you might want to install setuptools manually.

4.2.2.3.3 pyprocgame Dependencies

   easy_install PIL
   easy_install PyYAML

Note - PyYAML.org was down when this setup guide was made; so PyYAML was actually installed manually (download, scp it onto Beaglboard, unzip, run "python setup.py install")

4.2.2.3.4 proc-shared

   git clone git://github.com/preble/proc-shared.git

4.2.2.3.5 pyglet (optional)

   easy_install pyglet

• Note - I ran into this bug and the package recommended in the comments did not fix it. I've therefore uninstalled pyglet from my board. If you figure out a way to get pyglet working, please edit this section with instructions.

4.2.2.3.6.1 pygame Dependencies

   sudo apt-get install libsdl1.2-dev libsdl-ttf2.0-dev libsdl-image1.2-dev libsdl-mixer1.2-dev libportmidi-dev libv4l-dev

4.2.2.3.6.2 pygame

Due to a dependency issue, pygame could not be installed using easy_install. So, download pygame, scp it over, and unzip it. Then edit src/camera.h and change:

from:

   #include <linux/videodev.h>

to:

   #include <libv4l1-videodev.h>

Now run from the top pygame directory:

   sudo python setup.py install

4.2.2.3.7 pyprocgame configuration file

   mkdir ~/.pyprocgame

Now create and edit a "config.yaml" file with your pyprocgame configuration parameters. Refer to the pyprocgame's System Configuration File documentation for specifics.

4.2.2.3.8 desktop support (for graphics like virtual DMDs)

The master 1.0 branch of pyprocgame expects a desktop to be installed. If one is not installed, scripts will fail when attempting to load pyglet or pygame. If you want to install the ubuntu desktop:

   sudo apt-get install ubuntu-desktop

Be aware, it's a pretty big resource hog. If you don't need it, I'd recommend not installing it.

If you haven't installed a desktop and don't want to, you can switch to the dev branch of pyprocgame. From the pyprocgame directory:

   git checkout dev

Now add the following line to your ~/.pyprocgame/config.yaml file:

   use_desktop: False

Now the pyprocgame scripts you run will not attempt to pull in pyglet or pygame. If you want to use pygame's mixer for sound playback, you still can. You just have to import it directly into your script. I've never used pyglet; so I don't know if there's a similar solution for sound with it.

4.2.2.4 P-ROC udev

To allow software to control the P-ROC without running everything with 'sudo', you'll need to add a udev entry for the board. Create the file /etc/udev/rules.d/50-P-ROC.rules with the following contents:

   SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", SYSFS{idVendor}=="0403", SYSFS{idProduct}=="6001", MODE:="0666", GROUP="users"

4.2.2.5 Conclusion

That should be it. You should now be able to run pyprocgame scripts to control a P-ROC.

4.3 Chumby

4.3.1 Links

• Adafruit.com

4.4 ODROID

4.4.1 Links

• ODROID-U3

4.5 Raspberry Pi

4.5.1 Links

• Raspberry Pi
• Amazon.com

4.5.2 Raspberry Pi Setup Guide

Using a Raspberry Pi with P-ROC is not much different than using any other Linux OS. Using the directions on the Linux Build Instructions page should result in a fully-functional environment (keeping in mind that the Raspberry Pi is a pretty under-powered device in general).

You can also download and use the debian toolkit to automatically install everything from the dependencies through libpinproc, pypinproc, and pyprocgame.

The model of Raspberry pi tested was a Model B, Rev 2. The OS used is Raspbian, which is available from http://downloads.raspberrypi.org/raspbian_latest. The specific version of Raspbian used for this test is based on Debian Wheezy. Any other versions (updates or old versions) might change things.

Copying the image to your Raspberry Pi can be accomplished by following the instructions provided on the same download page, or just follow these links:

Install from Linux

Install from Mac

Install from Windows

Once this process is complete, run through initial setup process. Then start building the pinproc components!

5 Linux Build Instructions

This was created by Gabe Knuth (just so you don't direct questions at Gerry).

The following are instructions for building libpinproc and pypinproc on Linux. These instructions have been tested with various flavors of Debian, including various versions of Ubuntu (including 14.04) and Xubuntu, as well as Debian Wheezy. It has worked on many different types of hardware, including Raspberry Pi, Mini-ITX, and ODROID, as well as in Parallels Desktop and VMWare Fusion virtual machines.

If you want to take the more automated approach, you can download the debian toolkit here. Follow the instructions there to install (it's really easy).

If you use any other build, distro, or hardware platform your mileage may vary. Also, I’m no Linux guy, so if I don’t use the right terms or do something stupid, let me know so we can change the procedure. All of this work was done in the terminal. If you have a GUI, feel free to replace steps with their GUI equivalent.

Throughout this article you'll see references to <filename> and <directory>. Since the specific names of the files you'll download can change, I've left these in as placeholders. Essentially, whatever file you download, that's what you put in place of <filename> in the command line. Typically after extracting that file, a directory will be created that is very similar to the file name. You can see this by typing "ls" without the quotes at the command prompt. That new directory is the name that you use in place of <directory>. Forgive me if that's obvious, but I just wanted to make sure that everyone understands what I mean from the saltiest old Linux guy to the person who barely knows that it exists.

5.1 Prerequisite Packages

1. Upgrade your apt-get repositories:

sudo apt-get update

2. Install libudev-dev

sudo apt-get install libudev-dev

3. Download and compile libusbx-1.xxx.

Download the bits from: http://sourceforge.net/projects/libusbx/

tar -xjf <filename>
cd <directory>
./configure
make
sudo make install

4. Install libusb-dev

sudo apt-get install libusb-dev

5. Download and compile libusb-1.x. (Note this is slightly different than Step 3, which is libusbX). In late April 2014, this file (version 1.0.18) could not be opened via the tar -xjf command due to an oddball problem. It had to be opened on a Mac or Windows machine, then transferred via thumb drive or network drive mapping.

Download bits from http://www.libusb.org/

tar -xjf <filename>
cd <directory>
./configure
make
sudo make install

6. Install cmake

sudo apt-get install cmake

7. Download and compile libftdi1

Download bits from http://www.intra2net.com/en/developer/libftdi/download.php (There are many versions of ftdi. This is the one you want, so don’t just google for it.)

tar -xjf <filename>
cd <directory>
mkdir bin
cd bin
cmake ..
make
sudo make install

8. Install g++ (It’s probably installed already, but do this just to make sure)

sudo apt-get install g++

9. Install python-dev

sudo apt-get install python-dev

10. Install python-setuptools

sudo apt-get install python-setuptools

11. Download and compile yaml-cpp.

There are many versions of YAML. They switched the API after version 3.0, so you want to use 3.0 or under. Downloads bits from https://code.google.com/p/yaml-cpp/downloads/list. Installing YAML takes a long time, like 20 mins.

tar -xzf <filename> (note the parameter change - this is a gzip file, not a bz2 file)
cd <directory>
mkdir bin
cd bin
cmake ..
make
sudo make install

12. Set up Environment Variables

This step is more or less necessary. You could edit the CMakeLists.txt file and setup.py files for the next few packages, but setting the paths makes things much easier. Simply cutting and pasting the below commands should do everything you need.

export C_INCLUDE_PATH=$(find /usr/ -name ftdi.h -printf '%h\072')
export CPLUS_INCLUDE_PATH=$(find /usr/ -name ftdi.h -printf '%h\072')
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
echo "export LD_LIBRARY_PATH="$LD_LIBRARY_PATH >> ~/.bashrc
echo "export C_INCLUDE_PATH="$C_INCLUDE_PATH >> ~/.bashrc
echo "export CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH >> ~/.bashrc

What's happening here is that we have to build up some environment variables so that libpinproc and pypinproc know where to look for things. Specifically, it's looking for the usb and ftdi drivers that actually connect to the P-ROC. These commands find the ftdi.h file so you don't have to know where it is and add it to the C_INCLUDE_PATH and CPLUS_INCLUDE_PATH environment variables. As for LD_LIBRARY_PATH, this tells the linker (part of compiling process) where it can find the libpinproc libraries. We know this is in /usr/local/lib, so it's hardcoded.

Then, the "echo..." commands add those paths to your profile so that every time you log in or start a new terminal session those environment variables are there.

13. Give normal users rights to ftdi drivers

The last thing we have to do before moving on to the pinball-specific stuff is to give normal users access to the ftdi and usb drivers. You can do this step now, but you'll have to reboot at some point. You don't have to do it before continuing, but at some point you'll need to reboot before you can run your game.

You'll need to create a file somewhere called 50-P-ROC.rules. Inside this file, you'll want to enter the following lines:

SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666", GROUP="users"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE:="0666", GROUP="users"

Save the file, then copy the it to the /etc/udev/rules.d folder (you'll need root access to do this):

sudo cp 50-P-ROC.rules /etc/udev/rules.d

rules.d isn't processed until boot, so remember to reboot at some point.

5.2 Pinball-Specific Stuff

You've made it through the hard stuff! It's smooth sailing from here (probably).

5.2.1 libpinproc

This process was done with libpinproc-master, but you can also use libpinproc-dev. It’s available from https://github.com/preble/libpinproc. Make sure that you pick the proper branch (dev or master), then click “Download Zip” on the right side of the screen. The dev branch may have a few differences in this process as it relates to the CMakeList.txt file, but you should be able to figure it out. Run it first and see what happens.

Unzip your file using and switch into that directory:

unzip <filename>
cd <directory>

When that’s done, it’s time to compile. Cross your fingers and run:

mkdir bin
cd bin
cmake -DBUILD_SHARED_LIBS=”ON”  ..
make
sudo make install

If you succeed, congrats! Move on to the pypinproc section.

If not, check the error. If it says something isn’t found, see if you can find it. The errors are usually pretty cryptic, like “cannot find -lusb”. In that specific situation, make sure you installed libusb-dev above and have the environment variables set up properly (you can type "export" from the command line to check them). If you have other errors, see if it references a file (like ftdi.h). Then try to find that file. Here’s one way to search the filesystem for a file:

cd /
sudo find . -name <filename>

It will respond with the path of any occurrences of that file. Usually, the one you want is somewhere in the /usr tree. Make a note of that path and add it to the the environment variables as described above. You could also add it to the CMakeLists.txt file's include_directories line, but if you do that you'll always have to edit that file if you ever want to update libpinproc.

From there, recompile libpinproc. You may not have to do this, but I did it just in case. From the libpinproc directory, do:

rm -r bin

...then follow the compile instructions above again (starting with “mkdir bin”). Again, this might not be necessary, but it worked for me.

5.2.2 pypinproc

Thankfully, this part is much easier. Download pypinproc from https://github.com/preble/pypinproc. Make sure that you pick the proper branch (dev or master), then click “Download Zip” on the right side of the screen.

Unzip your file using and switch into that directory:

unzip <filename>
cd <directory>

After that, you’re ready to install:

sudo python setup.py install

Again, if you have errors, look for file names, find the files, and add the paths, just like in libpinproc.

5.2.3 pyprocgame

As long as you set up the environment variables (the last step before moving to the pinball-specific stuff), you're all set to install pyprocgame. Download it from https://github.com/preble/pyprocgame, again choosing the proper branch (dev or master). Unzip your file, switch into that directory, and install:

unzip <filename>
cd <directory>
sudo python setup.py install

5.2.4 PyYAML

Download PyYAML from http://pyyaml.org/download/pyyaml/. The version used for this document was 3.10, but 3.x should work just fine.

tar -xzf <filename>
cd <directory>
sudo python setup.py install

5.2.5 pygame

pygame is a more flexible alternative to pyglet that does not require OpenGL to do anything. The main benefit of using pygame on the Raspberry Pi is that since it doesn’t require OpenGL, you’ll be able to use the desktop DMD, albeit a less functional one. If you choose to use pyglet, see the instructions below.

Pygame is installed by default in Raspbian, but you may need to install SDL If you have a problem. Try your game without SDL, but if you require it, follow these instructions:

To install SDL (I used version 1.2), download it from http://www.libsdl.org/download-1.2.php

tar -xjf <filename>
cd <directory>
./configure
make
sudo make install

5.2.6 PIL

You’ll know you need this if you try to run your game and get an error looking for a module called IMAGES.

Download the package from http://effbot.org/downloads/Imaging-1.1.7.tar.gz

tar -xzf <filename>
cd <directory>
sudo python setup.py install

5.3 Loose Ends

At this point, you can probably run your game, but if you do you’ll likely get errors looking for other modules. Here are some of the modules that people require. You may not require them, or you might require more. The basic process is the same–chase them down and install them.

5.3.1 OSC

You’ll know you need this if you try to run your game and get an error looking for a module called OSC or if you already know that your game is using the OSC capabilities that allow you to control your game through an OSC interface (like TouchOSC on iOS devices).

There are many OSC libraries for python. You want pyOSC, available from https://trac.v2.nl/wiki/pyOSC. The version used here is 0.3.5b.

tar -xzf <filename>
cd <directory>
sudo python setup.py install

5.3.2 GLU

You’ll know you need this if you try to run your game and get an error looking for a module called GLU. This is easy to get, just run:

sudo apt-get install freeglut3-dev

5.3.3 pyglet

pyglet is a python library which handles windows, graphics, and inputs that pyprocgame uses. You can download it from http://www.pyglet.org/download.html. You’ll need the tar.gz version (scroll down a bit). Games typically run on the pygame library, however there are some reasons to choose pyglet over pygame. What you actually do, though (and why), is outside the scope of this article. pyglet's presence overrides pygame, only install pyglet if you know you need it.

tar -xzf <filename>
cd <directory>
sudo python setup.py install

Unfortunately, pyglet uses OpenGL in X Window to show the desktop DMD, which isn’t supported on Raspberry Pi (or at least in Raspbian). If you want to use the desktop DMD, this is not the solution for you. You should use pygame instead.