remote-rig/README.md

# RemoteRig Central Hub

A central hub for managing remote camera rigs, designed for Raspberry Pi Zero 2 W.

## Overview

RemoteRig Central Hub is the control plane for remote camera setups. It connects to camera rigs over MQTT, stores configuration and state in SQLite, and exposes a management API — all from a lightweight Go binary optimized for resource-constrained devices like the Raspberry Pi Zero 2 W.

## Tech Stack

| Component      | Technology                    |
| -------------- | ----------------------------- |
| Language       | Go 1.24+                      |
| Database       | SQLite                        |
| Messaging      | MQTT                          |
| Configuration  | YAML (`gopkg.in/yaml.v3`)     |
| Target Platform| Raspberry Pi Zero 2 W (ARMv6) |

## Project Structure

```
remote-rig/
├── cmd/
│   └── server/
│       └── main.go         # Application entry point
├── internal/
│   └── db/
│       └── db.go           # SQLite database initialization and schema
├── config.yaml             # Application configuration
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
└── README.md
```

## Prerequisites

- **Go 1.24+** — [Download and install](https://go.dev/dl/)
- **MQTT Broker** — e.g., [Mosquitto](https://mosquitto.org/) (default: `localhost:1883`)
- **Raspberry Pi Zero 2 W** (or any Linux system — macOS and Windows also work for development)
- **Git** — for cloning the repository

## Setup

### 1. Clone the Repository

```bash
git clone https://code.cubecraftcreations.com/CubeCraft-Creations/remote-rig.git
cd remote-rig
```

### 2. Install Go Dependencies

```bash
go mod download
```

### 3. Configure

Edit `config.yaml` to match your environment:

```yaml
# Database file path (SQLite)
db_path: "remoterig.db"

# API key for endpoint authentication — CHANGE THIS
api_key: "your-secure-api-key-here"

# HTTP server settings
port: 8080
read_timeout: 5s
write_timeout: 10s
idle_timeout: 120s

# MQTT broker connection
mqtt:
  broker: "localhost:1883"
  client_id: "remoterig-hub"

# Target platform
platform:
  type: "pi-zero-2w"
  max_cameras: 16
```

Key settings to review:

| Setting | Description | Default |
| ------- | ----------- | ------- |
| `api_key` | API key for authenticating requests | `changeme` (**must change**) |
| `port` | HTTP server listen port | `8080` |
| `mqtt.broker` | MQTT broker address | `localhost:1883` |
| `mqtt.client_id` | MQTT client identifier | `remoterig-hub` |
| `platform.type` | Target platform identifier | `pi-zero-2w` |
| `platform.max_cameras` | Maximum number of camera rigs | `16` |
| `db_path` | SQLite database file path | `remoterig.db` |
| `read_timeout` | HTTP read timeout | `5s` |
| `write_timeout` | HTTP write timeout | `10s` |
| `idle_timeout` | HTTP idle connection timeout | `120s` |

## Running Locally

Start the hub with:

```bash
go run ./cmd/server/
```

You should see output similar to:

```
RemoteRig hub starting...
Database: remoterig.db
API key set: true
Server port: 8080
MQTT broker: localhost:1883
Platform: pi-zero-2w (max 16 cameras)
RemoteRig hub ready
```

## Deployment (CI/CD — pull-based)

Deploys are automated and pull-based, so nothing has to reach into the closed
RemoteRig network:

1. **Push to `dev`** → Gitea Actions (`.gitea/workflows/build-dev.yaml`) builds the
   React frontend and cross-compiles the Go hub for **arm64**.
2. The workflow publishes the binary + `sha256` + `version.txt` to a rolling
   **`dev` release**.
3. On the Pi, `remoterig-update.timer` runs `scripts/pi-update.sh` every few
   minutes: it compares versions, downloads + verifies the checksum, and installs
   via `scripts/deploy.sh` (backup → restart → rollback on failure).

First-time Pi setup (`sudo scripts/setup-pi.sh`) installs Mosquitto, the
`remoterig` service, and the updater timer. If the repo is private, set a read
token in `/opt/remoterig/update.env`.

### Manual / local cross-compile

The Pi Zero 2 W is a Cortex-A53 (ARMv8) running 64-bit Raspberry Pi OS, so the
target is **arm64**:

```bash
GOOS=linux GOARCH=arm64 go build -o remoterig-hub ./cmd/server/
scp remoterig-hub config.yaml pi@192.168.8.56:/opt/remoterig/
```

### Build Matrix

| Target | Command |
| ------ | ------- |
| Raspberry Pi Zero 2 W (64-bit OS) | `GOOS=linux GOARCH=arm64 go build -o remoterig-hub ./cmd/server/` |
| Raspberry Pi (32-bit OS) | `GOOS=linux GOARCH=arm GOARM=7 go build -o remoterig-hub ./cmd/server/` |
| Local (same arch) | `go build -o remoterig-hub ./cmd/server/` |
| Linux amd64 | `GOOS=linux GOARCH=amd64 go build -o remoterig-hub ./cmd/server/` |

## Running Tests

```bash
go test ./...
```

## License

Proprietary — CubeCraft Creations.