raspberry-pi-setup

# 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

```bash
sudo apt update && sudo apt upgrade -y
```

## Step 2: Enable GPIO

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

Or enable via the config file:
```bash
echo "dtparam=i2c_arm=on" | sudo tee -a /boot/config.txt
```

## Step 3: Add user to gpio group

```bash
sudo usermod -aG gpio $USER
newgrp gpio
```

Verify membership:
```bash
groups $USER
# Should include: gpio
```

## Step 4: Install Node.js 20 LTS

```bash
# 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

```bash
corepack enable
corepack prepare pnpm@latest --activate

# Verify
pnpm --version
```

## Step 6: Install pigpio system library

```bash
sudo apt install -y pigpio
```

Start the pigpiod daemon:
```bash
sudo pigpiod

# Verify
pgrep pigpiod  # Should print a process ID
```

Enable pigpiod at boot:
```bash
sudo systemctl enable pigpiod
sudo systemctl start pigpiod
```

## Step 7: Clone and install gpio-controller

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

## Step 8: Configure environment

Create a `.env` file or export variables:
```bash
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

```bash
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:
```bash
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:
```bash
sudo systemctl daemon-reload
sudo systemctl enable gpio-controller
sudo systemctl start gpio-controller

# Check status
sudo systemctl status gpio-controller
```

View logs:
```bash
journalctl -u gpio-controller -f
```

## Firewall configuration

Allow access from local network:
```bash
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:
```bash
hostname -I
# Prints: 192.168.1.42 (use this IP from other devices)
```

## Updating gpio-controller

```bash
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)