Skip to content

INSTALLATION_GUIDE.md

Latest commit

 

History

History
193 lines (147 loc) · 5.36 KB

INSTALLATION_GUIDE.md

File metadata and controls

193 lines (147 loc) · 5.36 KB

Between Threads - Complete Installation Guide

This guide explains how to install the complete Between Threads system using the Orchestrator scripts.

Overview

The Between Threads project consists of three main components:

  1. RaspberryPi-Software: Backend service with servo control and WebSocket API
  2. Dashboard: Web interface for monitoring and control
  3. Live-Streaming: Camera streaming service for remote puppet monitoring

Installation

Quick Install

Run the following command to install everything automatically:

curl -LsSf https://raw.githubusercontent.com/Between-Threads-Project/Orchestrator/main/install.sh | bash

Manual Install

  1. Clone the Orchestrator repository:

    git clone https://github.com/Between-Threads-Project/Orchestrator
cd Orchestrator

  2. Make the script executable:

    chmod +x install.sh

  3. Run the installation:

    ./install.sh

What the Install Script Does

1. System Preparation

  • Creates application directory at ~/Desktop/BetweenThreads
  • Installs system dependencies (git, curl, wget, build-essential, python3, nodejs, npm)
  • Installs uv (Python package manager)

2. Component Installation

  • RaspberryPi-Software: Clones repo and installs Python dependencies
  • Dashboard: Clones repo, installs npm dependencies, and builds production assets
  • Live-Streaming: Clones repo and verifies Node.js streaming server

3. pigpio Installation

  • Downloads, compiles, and installs the pigpio library for servo control
  • Creates a systemd service for automatic pigpio daemon startup

4. Service Configuration

Creates four systemd services:

  • pigpiod-custom.service: Runs the pigpio daemon
  • between-threads.service: Runs the main backend service
  • between-threads-dashboard.service: Runs the web dashboard
  • between-threads-livestream.service: Runs the camera streaming service

5. Service Management

  • Enables all services to start on boot
  • Starts all services immediately
  • Verifies service status
  • Handles ffmpeg dependency for camera streaming

Post-Installation

Access the System

  • Dashboard: http://<raspberry-pi-ip>:3000
  • API: http://<raspberry-pi-ip>:8000
  • Live Stream: http://<raspberry-pi-ip>:8000
  • UDP Ports: 5000, 5001 (for external hand recognition data)

Service Management

Check service status:

sudo systemctl status pigpiod-custom
sudo systemctl status between-threads
sudo systemctl status between-threads-dashboard
sudo systemctl status between-threads-livestream

Restart services:

sudo systemctl restart pigpiod-custom
sudo systemctl restart between-threads
sudo systemctl restart between-threads-dashboard
sudo systemctl restart between-threads-livestream

View logs:

sudo journalctl -u between-threads -f
sudo journalctl -u between-threads-dashboard -f
sudo journalctl -u between-threads-livestream -f

Uninstallation

To completely remove Between Threads:

curl -LsSf https://raw.githubusercontent.com/Between-Threads-Project/Orchestrator/main/uninstall.sh | bash

Or manually:

cd Orchestrator
chmod +x uninstall.sh
./uninstall.sh

The uninstall script will:

  • Stop and disable all services
  • Remove service files
  • Delete the application directory
  • Clean up the pigpio build directory
  • Remove uv installation (optional)

Troubleshooting

Common Issues

pigpio daemon not running:

sudo systemctl restart pigpiod-custom

Servo motors not moving:

  • Check GPIO connections
  • Verify power supply (5V)
  • Check UDP data is being received on correct ports

Dashboard not accessible:

  • Check if the service is running: sudo systemctl status between-threads-dashboard
  • Verify Node.js is installed: node --version
  • Check firewall settings

Permission issues: Ensure the script is run with sudo or that your user has passwordless sudo access.

Component Communication

External Hand-Recognition → UDP → RaspberryPi-Software → Servo Motors
                                    ↓
                                Dashboard ← WebSocket
                                    ↓
                                Live-Streaming ← Camera
  • External Hand-Recognition sends UDP data to ports 5000/5001 (from separate laptop)
  • RaspberryPi-Software controls servo motors via pigpio
  • Dashboard connects to RaspberryPi-Software via WebSocket (port 8000)
  • Dashboard provides user interface for monitoring and control
  • Live-Streaming captures camera feed and serves MJPEG stream on port 8000

Configuration

RaspberryPi-Software

Edit ~/Desktop/BetweenThreads/RaspberryPi-Software/core/utils.py to modify:

  • GPIO pin mappings
  • Servo pulse width ranges
  • UDP port configurations

Dashboard

Configuration is in the Next.js application files. Modify:

  • API endpoints in environment variables
  • UI components in the app/ directory

Live-Streaming

Edit the server.js file to modify:

  • Camera device path (default: /dev/video0)
  • Stream resolution and quality
  • Port configuration (default: 8000)
  • FFmpeg parameters for video encoding

Requirements

  • Raspberry Pi 3 Model B v1.2 (or compatible)
  • Raspberry Pi OS (or any Linux distribution)
  • Internet access for installation
  • Administrative rights (sudo)
  • PWM-compatible servo motors (e.g., SG90)

License

MIT License - See LICENSE.md for details.