> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# EdgeCaster RTSP Gateway

> Run EdgeCaster on a Raspberry Pi to convert Rhombus camera streams to RTSP for integration with legacy VMS, NVR, and third-party video management systems.

**EdgeCaster** is a lightweight edge gateway that converts Rhombus secure raw streams into RTSP streams using [MediaMTX](https://github.com/bluenviron/mediamtx). It runs on a Raspberry Pi 5 and allows legacy VMS, NVR, and third-party AI/video systems that require RTSP to consume video from Rhombus cameras.

<Warning>
  Rhombus does not support RTSP natively because it is not a secure protocol. EdgeCaster bridges this gap for environments that require RTSP compatibility by converting Rhombus's encrypted raw streams locally on your network. Deploy EdgeCaster only on trusted networks.
</Warning>

## How It Works

```text theme={null}
Rhombus Camera
     │
     │ Secure Raw Stream (HTTPS H.264)
     ▼
EdgeCaster (Raspberry Pi)
     │ FFmpeg stream copy (no transcoding)
     ▼
MediaMTX (RTSP server, port 8554)
     │
     ▼
External Systems (VMS / NVR / AI)
```

EdgeCaster uses the Rhombus API to discover cameras, creates secure raw streams via `createRawHttpStream`, and pipes them through FFmpeg (stream copy — no transcoding) to MediaMTX which serves them as standard RTSP.

## Features

* Automatic camera discovery via Rhombus API
* Web UI for enabling/disabling streams per camera
* Up to 10 concurrent streams (stream copy, no CPU-intensive transcoding)
* Automatic stream recovery on failure with configurable retry logic
* Persistent stream state across reboots
* Auto-updates via configurable nightly window
* Ready-to-flash Raspberry Pi SD card image builder

## Hardware Requirements

| Component   | Requirement           |
| ----------- | --------------------- |
| **Device**  | Raspberry Pi 5        |
| **RAM**     | 8 GB recommended      |
| **Storage** | 32 GB SD card minimum |
| **Network** | Gigabit Ethernet      |
| **OS**      | Ubuntu Server 24.04   |

## Setup

<Tabs>
  <Tab title="Install Script">
    <Steps>
      <Step title="Clone and install">
        ```bash theme={null}
        git clone https://github.com/RhombusSystems/edgecaster-stream-converter.git
        cd edgecaster-stream-converter
        sudo bash scripts/install.sh
        ```

        The installer handles all dependencies: FFmpeg, Python, Node.js, Nginx, MediaMTX, systemd services, and log rotation.
      </Step>

      <Step title="Configure via web UI">
        Open `http://<device-ip>` in a browser:

        1. Enter your Rhombus Org API Key
        2. Cameras are discovered automatically
        3. Toggle cameras on to start RTSP streams
      </Step>

      <Step title="Connect your systems">
        Point your VMS, NVR, or video analytics to the RTSP endpoints:

        ```text theme={null}
        rtsp://<device-ip>:8554/front_door
        rtsp://<device-ip>:8554/warehouse
        rtsp://<device-ip>:8554/parking_lot
        ```

        Test with VLC: `vlc rtsp://<device-ip>:8554/<stream-name>`
      </Step>
    </Steps>
  </Tab>

  <Tab title="SD Card Image">
    Build a ready-to-flash image instead of installing manually:

    ```bash theme={null}
    # Clone the repo on a build machine
    git clone https://github.com/RhombusSystems/edgecaster-stream-converter.git
    cd edgecaster-stream-converter

    # Cloud-init mode (smaller image, needs internet on first boot)
    sudo bash image/build-image.sh

    # Pre-baked mode (larger image, no internet needed)
    sudo bash image/build-image.sh --prebaked
    ```

    Flash the `.img.xz` file to an SD card with [Raspberry Pi Imager](https://www.raspberrypi.com/software/).

    On first boot the device:

    * Sets hostname to `edgecaster`
    * Creates the `edgecaster` user (default password: `edgecaster`)
    * Installs dependencies and starts services
    * Is accessible at `http://edgecaster.local`

    <Warning>
      Change the default password immediately after first login: `passwd edgecaster`
    </Warning>
  </Tab>
</Tabs>

## Web UI

The web interface at `http://<device-ip>` provides:

* **Dashboard** — View all discovered cameras with stream status
* **Stream control** — Toggle individual cameras on/off for RTSP conversion
* **Settings** — Configure API key, refresh camera discovery, set auto-update window
* **System status** — Health metrics and service status

<Note>
  The web UI has no built-in authentication in v1. Deploy EdgeCaster only on trusted networks where access to port 80 is restricted.
</Note>

## Network Ports

| Port     | Purpose                                |
| -------- | -------------------------------------- |
| **80**   | Web UI (Nginx reverse proxy)           |
| **8554** | RTSP streams (MediaMTX)                |
| 8000     | Backend API (internal, localhost only) |

## Rhombus API Endpoints Used

EdgeCaster interacts with 5 Rhombus API endpoints automatically:

| Endpoint                                     | Purpose                                 |
| -------------------------------------------- | --------------------------------------- |
| `POST /api/camera/getMinimalCameraStateList` | Discover cameras in your organization   |
| `POST /api/camera/createRawHttpStream`       | Create a secure raw stream for a camera |
| `POST /api/camera/deleteRawHttpStream`       | Clean up stream when disabled           |
| `POST /api/camera/getRawHttpStreams`         | List existing raw streams               |
| `POST /api/location/getLocationLabelsForOrg` | Resolve location names for the UI       |

## Managing Services

EdgeCaster runs as systemd services:

```bash theme={null}
# Check status
sudo systemctl status edgecaster
sudo systemctl status mediamtx

# View logs
journalctl -u edgecaster -f
journalctl -u mediamtx -f

# Restart
sudo systemctl restart edgecaster
```

## Auto-Updates

EdgeCaster checks for updates hourly and applies them during a configurable window (default: 2:00–5:00 AM). Configure via the web UI Settings page or directly:

```yaml theme={null}
# /etc/edgecaster/config.yaml
auto_update_enabled: true
update_hour_start: 2
update_hour_end: 5
```

Manual update:

```bash theme={null}
sudo bash scripts/edgecaster-update.sh
```

## Local Development

<CodeGroup>
  ```bash Backend theme={null}
  python3 -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt
  cd backend
  uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
  ```

  ```bash Frontend theme={null}
  cd frontend
  npm install
  npm run dev
  # Dev server on http://localhost:5173, proxies /api to backend
  ```

  ```bash Tests theme={null}
  pip install pytest pytest-asyncio
  python -m pytest backend/tests/ -v
  ```
</CodeGroup>

## EdgeCaster API

The EdgeCaster backend exposes a local REST API:

| Method | Path                              | Description                      |
| ------ | --------------------------------- | -------------------------------- |
| `GET`  | `/api/auth/status`                | Check setup state                |
| `GET`  | `/api/settings`                   | Get app settings                 |
| `POST` | `/api/settings/api-key`           | Set Rhombus API key              |
| `PUT`  | `/api/settings/update-schedule`   | Configure auto-update window     |
| `POST` | `/api/settings/discovery/refresh` | Refresh camera list from Rhombus |
| `GET`  | `/api/cameras`                    | List discovered cameras          |
| `GET`  | `/api/streams`                    | List active RTSP streams         |
| `POST` | `/api/streams/{uuid}/enable`      | Start RTSP stream for a camera   |
| `POST` | `/api/streams/{uuid}/disable`     | Stop RTSP stream                 |
| `GET`  | `/api/system/status`              | System health metrics            |

## Limitations

* Maximum 10 concurrent streams (Raspberry Pi CPU constraint, configurable via `max_streams`)
* RTSP authentication is not enabled in v1 — restrict access via network controls
* Cameras must be accessible on the local network for raw stream URLs
* Secure raw stream tokens expire automatically; EdgeCaster recreates them on failure
* No HTTP authentication on the web UI — trusted network deployment only

## Security Notes

* Your API key is stored in `/etc/edgecaster/config.yaml` (owned by `edgecaster` user, not world-readable)
* API keys are never logged or exposed in API responses
* The systemd service runs with hardened security: `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome`, `PrivateTmp`
* RTSP streams are unauthenticated — restrict port 8554 access at the network level

## Troubleshooting

<AccordionGroup>
  <Accordion title="No cameras found">
    Verify your Rhombus API key is valid and has access to cameras. Check that the device can reach `api2.rhombussystems.com`. Try refreshing discovery from the Settings page.
  </Accordion>

  <Accordion title="Stream not starting">
    Check FFmpeg is installed (`ffmpeg -version`), MediaMTX is running (`systemctl status mediamtx`), and the camera is online. View logs with `journalctl -u edgecaster -f`.
  </Accordion>

  <Accordion title="RTSP URL not working">
    Confirm the stream shows "running" in the web UI. Test with VLC: `vlc rtsp://<device-ip>:8554/<path>`. Check that port 8554 is not blocked by a firewall.
  </Accordion>

  <Accordion title="Auto-update not running">
    Check the timer: `systemctl status edgecaster-update.timer`. Verify the installation is git-based (`.git` folder exists) and the current time falls within the update window.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/RhombusSystems/edgecaster-stream-converter">
    Source code, image builder, and issue tracker
  </Card>

  <Card title="Streaming Video Guide" icon="video" href="/implementations/streaming-video">
    Direct streaming integration without RTSP conversion
  </Card>

  <Card title="React SDK" icon="react" href="/implementations/react-sdk">
    Embed camera streams in React applications
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Full documentation for raw stream and camera endpoints
  </Card>
</CardGroup>