generated from CubeCraft-Creations/Tracehound
Joshua King
c2a05f9b7c
The Pi is on a closed travel-router LAN, so push-based deploy from a
runner can't reach it. Switch to pull: the runner builds + publishes,
the Pi fetches.
- build-dev.yaml: after the arm64 build, publish the binary + sha256 +
version.txt to a rolling "dev" Gitea release (replaces the
upload-artifact + repository_dispatch -> deploy-dev hop)
- remove deploy-dev.yaml (push/scp-based deploy no longer used)
- scripts/pi-update.sh: poll the dev release, verify sha256, install via
deploy.sh (backup/restart/rollback); only updates when version changes
- scripts/remoterig-update.{service,timer}: run the updater every 5 min
- setup-pi.sh: install deploy.sh + pi-update.sh + update.env template +
the updater timer; summary now reflects the pull flow
- README: document the pull-based CI/CD; fix stale GOARM=6 (Zero 2 W is
arm64 on 64-bit OS / arm GOARM=7 on 32-bit)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
165 lines
4.7 KiB
Markdown
165 lines
4.7 KiB
Markdown
# 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.
|