raspberry-pi-setup

name	raspberry-pi-setup
description	Preparing a Raspberry Pi to run gpio-controller. Use when you need to set up Node.js, enable GPIO, install pigpio, configure the pigpiod daemon, or set up a systemd service for auto-start. Triggers include "setup Pi", "install gpio-controller", "raspberry pi setup", "pigpio install", "systemd service", "autostart", or any task about preparing the Pi environment.

raspberry-pi-setup

Prepare a Raspberry Pi to run gpio-controller. Covers OS setup, Node.js installation, GPIO library installation, and systemd service configuration.

Supported hardware

• Raspberry Pi 4 Model B (recommended)
• Raspberry Pi 3 Model B/B+
• Raspberry Pi Zero 2 W
• Raspberry Pi 5 (pigpio may require additional steps)

OS requirements

• Raspberry Pi OS (64-bit recommended)
• Kernel 5.x or later
• User in the gpio group

Step 1: Update the system

sudo apt update && sudo apt upgrade -y

Step 2: Enable GPIO

sudo raspi-config
# Navigate to: Interface Options > GPIO > Enable

Or enable via the config file:

echo "dtparam=i2c_arm=on" | sudo tee -a /boot/config.txt

Step 3: Add user to gpio group

sudo usermod -aG gpio $USER
newgrp gpio

Verify membership:

groups $USER
# Should include: gpio

Step 4: Install Node.js 20 LTS

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version  # Should print v20.x.x

Step 5: Install pnpm

corepack enable
corepack prepare pnpm@latest --activate

# Verify
pnpm --version

Step 6: Install pigpio system library

sudo apt install -y pigpio

Start the pigpiod daemon:

sudo pigpiod

# Verify
pgrep pigpiod  # Should print a process ID

Enable pigpiod at boot:

sudo systemctl enable pigpiod
sudo systemctl start pigpiod

Step 7: Clone and install gpio-controller

cd ~
git clone <repo-url> gpio-controller
cd gpio-controller
pnpm install

Step 8: Configure environment

Create a .env file or export variables:

export PORT=4800
export DATA_DIR=/home/pi/gpio-controller/data
export MOCK_GPIO=0
export HISTORY_MAX_ROWS=10000

Step 9: Test the installation

pnpm start
# Should see: gpio-controller ready at http://localhost:4800

Open from another device:

http://raspberrypi.local:4800

Step 10: Set up systemd service for auto-start

Create the service file:

sudo tee /etc/systemd/system/gpio-controller.service << 'EOF'
[Unit]
Description=gpio-controller
After=network.target pigpiod.service
Requires=pigpiod.service

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/gpio-controller
Environment=PORT=4800
Environment=DATA_DIR=/home/pi/gpio-controller/data
Environment=MOCK_GPIO=0
Environment=HISTORY_MAX_ROWS=10000
ExecStart=/usr/bin/node packages/server/dist/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable gpio-controller
sudo systemctl start gpio-controller

# Check status
sudo systemctl status gpio-controller

View logs:

journalctl -u gpio-controller -f

Firewall configuration

Allow access from local network:

sudo ufw allow 4800/tcp
sudo ufw reload

Finding the Pi on your network

If mDNS is working:

http://raspberrypi.local:4800

Find IP address:

hostname -I
# Prints: 192.168.1.42 (use this IP from other devices)

Updating gpio-controller

cd ~/gpio-controller
git pull
pnpm install
pnpm build
sudo systemctl restart gpio-controller

Troubleshooting

pigpiod fails to start

• Check if another instance is running: sudo killall pigpiod
• Check permissions: ls -la /dev/gpiochip0
• Verify GPIO is enabled in raspi-config

Node.js cannot access GPIO

• Add user to gpio group (Step 3)
• Check /dev/gpiomem permissions: ls -la /dev/gpiomem
• If needed: sudo chmod a+rw /dev/gpiomem

Service fails to start

• Check journal: journalctl -u gpio-controller -n 50
• Verify pnpm path: which node and update ExecStart accordingly
• Check DATA_DIR exists and is writable

onoff import fails on Pi 5

• Pi 5 uses a different GPIO chip (gpiochip4)
• May need onoff v7 or later
• Alternative: use pigpio library only with MOCK_GPIO=0

Recommended power setup

• Use a quality 5V/3A power supply for Pi 4
• Do not power high-current devices (motors, relays) directly from GPIO pins
• Use appropriate driver boards (L298N, ULN2003) for motors and relays
• Keep total GPIO current draw below 50 mA (sum of all pins)