CUB-208: Add README with project overview and setup instructions

2026-05-21 17:47:29 +00:00
parent 69b050b62b
commit 861aedd6d8
1 changed files with 156 additions and 0 deletions
@@ -0,0 +1,156 @@
+# 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
+```
+
+## Building for Raspberry Pi Zero 2 W
+
+Cross-compile from your development machine:
+
+```bash
+GOOS=linux GOARCH=arm GOARM=6 go build -o remoterig-hub ./cmd/server/
+```
+
+Copy the binary and `config.yaml` to your Pi:
+
+```bash
+scp remoterig-hub config.yaml pi@raspberrypi:/home/pi/remoterig/
+```
+
+Then run on the Pi:
+
+```bash
+./remoterig-hub
+```
+
+### Build Matrix
+
+| Target | Command |
+| ------ | ------- |
+| Raspberry Pi Zero 2 W | `GOOS=linux GOARCH=arm GOARM=6 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.