Documentation

Setup Guide

Complete hardware wiring and software installation guide for your Autobowl system.

Step 0: Get the 3D Printed Parts

This project requires the Mini Tabletop Bowling 3D printed automatic pinsetter files from Kickstarter. All mechanical components are 3D printed — no additional hardware needed except the PCA9685 servo driver board.

View Kickstarter Project

Hardware Requirements

The only electronic component you need to purchase separately is the PCA9685 servo driver board. All other components (servos, sensors, LEDs) are included with the Kickstarter kit or are standard Raspberry Pi accessories.

Main Controller

Raspberry Pi 4

2GB+ RAM recommended
MicroSD card (16GB+)
USB-C power supply (5V 3A)
HDMI display (optional)

PCA9685 PWM Board

16-channel, 12-bit PWM driver via I2C for reliable servo control

7 Servos

Deck raise, slide, scissors, sweep arms, ball return

Stepper Motor

Turret control with Hall effect sensor for homing

Sensors

IR sensor (pins), ball sensor, Hall effect (turret home)

WS2812B LEDs

300 addressable RGB LEDs for lane lighting effects

Servo Channel Mapping

Channel	Servo	Function
0	Left Raise	Deck height (left side)
1	Right Raise	Deck height (right side)
2	Slide	Deck forward/back movement
3	Scissors	Pin grab/release mechanism
4	Left Sweep	Lane sweep arm (left)
5	Right Sweep	Lane sweep arm (right)
6	Ball Return	Ball return door

Wiring Diagrams

                Raspberry Pi 4 GPIO Header
                ┌─────────────────────────┐
         3.3V ──│ 1                     2 │── 5V
(I2C SDA) GPIO2 │ 3  ← PCA9685 SDA     4 │── 5V
(I2C SCL) GPIO3 │ 5  ← PCA9685 SCL     6 │── GND
      GPIO4     │ 7                     8 │── GPIO14 (TX)
          GND ──│ 9                    10 │── GPIO15 (RX)
      GPIO17    │11                    12 │── GPIO18
      GPIO27    │13                    14 │── GND
      GPIO22    │15                    16 │── GPIO23
         3.3V ──│17                    18 │── GPIO24
     (MOSI)     │19                    20 │── GND
     (MISO)     │21                    22 │── GPIO25
     (SCLK)     │23                    24 │── GPIO8 (CE0)
          GND ──│25                    26 │── GPIO7 (CE1)
       (ID_SD)  │27                    28 │── (ID_SC)
      GPIO5     │29                    30 │── GND
   Step GPIO6   │31                    32 │── GPIO12
Direction GPIO13│33                    34 │── GND
HallSensor GPIO19│35                    36 │── GPIO16 (Ball Sensor)
 IRSensor GPIO26│37                    38 │── GPIO20 (Conveyor)
          GND ──│39                    40 │── GPIO21 (WS2812 LEDs)
                └─────────────────────────┘

PCA9685 Board                    Raspberry Pi
┌────────────────┐              ┌──────────────┐
│      VCC       │──────────────│ 3.3V (Pin 1) │
│      GND       │──────────────│ GND  (Pin 6) │
│      SDA       │──────────────│ GPIO2 (Pin 3)│
│      SCL       │──────────────│ GPIO3 (Pin 5)│
│                │              └──────────────┘
│  V+ (Servo Pwr)│──── External 5V Power Supply (2A+ per servo)
│                │
│  Channel 0 ────│──── Left Raise Servo Signal
│  Channel 1 ────│──── Right Raise Servo Signal
│  Channel 2 ────│──── Slide Servo Signal
│  Channel 3 ────│──── Scissors Servo Signal
│  Channel 4 ────│──── Left Sweep Servo Signal
│  Channel 5 ────│──── Right Sweep Servo Signal
│  Channel 6 ────│──── Ball Return Servo Signal
└────────────────┘

Each servo connects:
• Signal (orange/yellow) → PCA9685 channel PWM pin
• VCC (red) → PCA9685 V+ rail
• GND (brown/black) → PCA9685 GND rail

Important: Do NOT power servos from Pi's 5V pins! Use an external 5V power supply (2A+ per servo) connected to V+ terminal.

Stepper Driver (A4988/DRV8825)      Raspberry Pi
┌──────────┐                       ┌──────────────┐
│   STEP   │───────────────────────│ GPIO6  (31)  │
│   DIR    │───────────────────────│ GPIO13 (33)  │
│   GND    │───────────────────────│ Any GND pin  │
│   VCC    │──── 5V Logic supply
│   VMOT   │──── Motor voltage (12-24V)
└──────────┘

Hall Effect Sensor (Turret Home)
┌──────────┐
│   VCC    │──── 3.3V (Pin 1 or 17)
│   GND    │──── GND
│   OUT    │───────────────────────│ GPIO19 (35)  │
└──────────┘     (internal pull-up enabled)

WS2812 LED Strip         Raspberry Pi
┌──────────┐            ┌──────────────┐
│   DIN    │────────────│ GPIO21 (40)  │
│   5V     │──── External 5V (3A+ for 300 LEDs)
│   GND    │────────────│ Any GND pin  │
└──────────┘

Power Warning: 300 LEDs at full white can draw up to 18A @ 5V. Use adequate power supply and wire gauge. WS2812 requires root access for DMA.

Ball Sensor (Digital)
┌──────────┐           Raspberry Pi
│   VCC    │──── 3.3V (Pin 1 or 17)
│   GND    │──── GND
│   OUT    │───────────│ GPIO16 (36)  │ (internal pull-up)
└──────────┘

IR Sensor (Pin Detection)
┌──────────┐
│   VCC    │──── 3.3V
│   GND    │──── GND
│   OUT    │───────────│ GPIO26 (37)  │ (internal pull-up)
└──────────┘

Conveyor Motor Relay
┌──────────┐           ┌──────────────┐
│   VCC    │──── 5V (external or Pi Pin 2/4)
│   GND    │───────────│ Any GND pin  │
│   IN     │───────────│ GPIO20 (38)  │
│   COM    │──── Motor power supply
│   NO     │──── Motor positive
└──────────┘

Software Setup

Quick Start (Cross-compile from Mac/Linux)

Build without WS2812 LED support for quick testing:

# Clone repository
git clone https://github.com/yourusername/autobowl.git
cd autobowl

# Build for Raspberry Pi 4 (64-bit)
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o autobowl-arm64 .

# Copy to Pi
scp autobowl-arm64 pi@<raspberry-pi-ip>:~/autobowl

# Run on Pi
ssh pi@<raspberry-pi-ip>
./autobowl

Build on Raspberry Pi (with LED support)

WS2812 LED control requires CGO and must be built on the Pi:

# Install dependencies
sudo apt update
sudo apt install -y golang git cmake build-essential

# Build WS2812 library
git clone https://github.com/jgarff/rpi_ws281x.git
cd rpi_ws281x
mkdir build && cd build
cmake .. && make
sudo make install
sudo ldconfig
cd ~

# Clone and build autobowl
git clone https://github.com/yourusername/autobowl.git
cd autobowl
CGO_ENABLED=1 go build -o autobowl .

# Run (requires root for WS2812 DMA access)
sudo ./autobowl

Enable I2C on Raspberry Pi

Required for PCA9685 servo board communication:

# Enable I2C interface
sudo raspi-config
# Navigate to: Interface Options → I2C → Enable

# Install I2C tools and verify PCA9685
sudo apt install -y i2c-tools
i2cdetect -y 1

# Should show device at address 0x40

Configuration

Servo Calibration

Access the debug page at http://<raspberry-pi-ip>:8080/debug to:

Adjust servo positions with sliders (0-180°)
Test stepper motor movement
Monitor sensor values in real-time
Trigger LED animations (Strike, Comet, etc.)

Web Interface URLs

/Main scoreboard display

/new-gameStart a new game

/playersPlayer management

/calibrationCamera pin calibration

/debugHardware diagnostics

LED Animation Modes

offAll LEDs off

idleSolid white

strikeRed wipe → Flash → White

comet4-LED white comet

greenSolid green (fill ball)

Troubleshooting

PCA9685 Not Detected

Check I2C is enabled via sudo raspi-config
Scan I2C bus: i2cdetect -y 1
Should show device at address 0x40
Check SDA/SCL wiring (GPIO2/GPIO3)
Verify VCC (3.3V) and GND connections

Servos Not Moving

Verify PCA9685 is detected via I2C
Check external 5V power supply to V+ on PCA9685
Ensure common ground between Pi, PCA9685, and power supply
Test with debug page slider at /debug
Check logs for "PCA9685 initialized" message

WS2812 LEDs Not Working

Must run with sudo for DMA access
Must be built on Pi with CGO_ENABLED=1
Check data pin connection (GPIO21)
Verify 5V power supply capacity (3A+ for 300 LEDs)
Check logs for "WS2812 initialized" message

Sensors Not Detecting

Check 3.3V power to sensor
Verify GND connection
Use debug page to view raw sensor values
Sensors use internal pull-ups (active LOW)
Test sensor output with multimeter

Back to Home