129 lines
5.4 KiB
Markdown
129 lines
5.4 KiB
Markdown
# Map and cameras
|
||
|
||
KestrelOS shows a **map** with **devices** (cameras, ALPR, NVR, etc.), **POIs**, **live sessions** (Share live), and **ATAK/iTAK** positions. You view streams by clicking markers or using the **Cameras** page.
|
||
|
||
---
|
||
|
||
## Using the map
|
||
|
||
- **Home:** The main view is the map (**/**). It uses OpenStreetMap-style tiles and supports offline tile caching (Leaflet.offline).
|
||
- **Layers:**
|
||
- **Devices** — Cameras and feeds you’ve added (API). Click a device marker to open the live stream in a side panel.
|
||
- **POIs** — Points of interest (admin/leader can add/edit from **POI** page).
|
||
- **Live sessions** — Mobile devices streaming via **Share live**. Click to view the live stream.
|
||
- **CoT (ATAK/iTAK)** — Amber markers for connected ATAK/iTAK devices (position only; no stream).
|
||
- **Actions:** Pan and zoom as usual. If you have permission, you can add/edit POIs from the **POI** page; device editing is via API (see below).
|
||
|
||
---
|
||
|
||
## What counts as a “camera”
|
||
|
||
In KestrelOS, a **camera** is either:
|
||
|
||
1. A **device** — A fixed feed (IPTV, ALPR, CCTV, NVR, doorbell, traffic cam, etc.) with a **stream URL** and optional config.
|
||
2. A **live session** — A mobile device streaming via **Share live** (WebRTC). These appear automatically while sharing.
|
||
|
||
The **Cameras** page (sidebar → **Cameras**) lists both: select an entry to view its stream in the panel. The map shows the same sources as markers; clicking a marker also opens the stream.
|
||
|
||
---
|
||
|
||
## Device types and stream types
|
||
|
||
When you add a **device** (via API), you set:
|
||
|
||
- **device_type** — One of: `alpr`, `nvr`, `doorbell`, `feed`, `traffic`, `ip`, `drone`. Used for labeling and filtering (e.g. “ALPR”, “NVR”).
|
||
- **source_type** — How the stream is delivered:
|
||
- **`mjpeg`** — MJPEG over HTTP (single image or MJPEG stream URL).
|
||
- **`hls`** — HLS (HTTP Live Streaming); use an `https://` or `http://` URL to an `.m3u8` playlist.
|
||
|
||
Stream URLs must be **http://** or **https://**; other protocols are rejected.
|
||
|
||
Examples by use case:
|
||
|
||
| Use case | device_type | source_type | stream_url example |
|
||
|----------|-------------|-------------|---------------------|
|
||
| IP camera / CCTV | `ip` or `feed` | `mjpeg` or `hls` | `http://192.168.1.10/mjpg/video.mjpg` |
|
||
| ALPR camera | `alpr` | `mjpeg` or `hls` | `https://alpr.example.com/stream.m3u8` |
|
||
| NVR feed | `nvr` | `mjpeg` or `hls` | `http://nvr.local/cam1/video.mjpeg` |
|
||
| Traffic camera | `traffic` | `mjpeg` or `hls` | `https://traffic.gov/cam123.m3u8` |
|
||
| Doorbell | `doorbell` | `mjpeg` or `hls` | As provided by vendor. |
|
||
| IPTV channel | `feed` | `hls` | `https://iptv.example.com/channel.m3u8` |
|
||
| Drone feed | `drone` | `mjpeg` or `hls` | As provided. |
|
||
|
||
---
|
||
|
||
## Adding and editing devices (API)
|
||
|
||
Only **admin** or **leader** can create or update devices. There is no “Add camera” form in the UI yet; use the HTTP API (e.g. from a script or tool).
|
||
|
||
### Create a device
|
||
|
||
**POST** `/api/devices`
|
||
Requires auth (session cookie). Body (JSON):
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `name` | string | Yes | Display name. |
|
||
| `device_type` | string | No | One of: `alpr`, `nvr`, `doorbell`, `feed`, `traffic`, `ip`, `drone`. Default `feed`. |
|
||
| `lat` | number | Yes | Latitude. |
|
||
| `lng` | number | Yes | Longitude. |
|
||
| `stream_url` | string | No | HTTP(S) URL for MJPEG or HLS. |
|
||
| `source_type` | string | No | `mjpeg` or `hls`. Default `mjpeg`. |
|
||
| `vendor` | string | No | Optional vendor/label. |
|
||
| `config` | string or object | No | Optional JSON config (stored as string). |
|
||
|
||
Example (curl, after logging in and saving cookie):
|
||
|
||
```bash
|
||
curl -X POST https://your-kestrelos.example.com/api/devices \
|
||
-H "Content-Type: application/json" \
|
||
-b "kestrelos.session=YOUR_SESSION_COOKIE" \
|
||
-d '{
|
||
"name": "Main gate ALPR",
|
||
"device_type": "alpr",
|
||
"lat": 37.7749,
|
||
"lng": -122.4194,
|
||
"stream_url": "https://alpr.example.com/stream.m3u8",
|
||
"source_type": "hls"
|
||
}'
|
||
```
|
||
|
||
### List devices
|
||
|
||
**GET** `/api/devices`
|
||
Returns all devices (auth required). The map and Cameras page use **GET** `/api/cameras`, which returns devices plus live sessions and CoT entities.
|
||
|
||
### Update a device
|
||
|
||
**PATCH** `/api/devices/:id`
|
||
Auth required. Send only the fields you want to change (e.g. `name`, `stream_url`, `lat`, `lng`, `device_type`, `source_type`).
|
||
|
||
### Delete a device
|
||
|
||
**DELETE** `/api/devices/:id`
|
||
Auth required.
|
||
|
||
---
|
||
|
||
## Viewing cameras
|
||
|
||
- **Map:** Click a device or live-session marker to open the stream in the side panel. Close the panel to return to the map.
|
||
- **Cameras page:** Open **Cameras** from the sidebar. The list shows all devices and live sessions; select one to view its stream in the right-hand panel. “Live” badge indicates an active Share live stream.
|
||
|
||
---
|
||
|
||
## POIs (points of interest)
|
||
|
||
Admins and leaders can add and edit POIs from the **POI** page (sidebar → **POI**). POIs appear on the map as pins. They are for reference only (no stream). Use **Map** for viewing and **POI** for managing the list and coordinates.
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
| Task | How |
|
||
|------|-----|
|
||
| View map and streams | Open **/** and click markers, or use **Cameras** page. |
|
||
| Add IPTV/ALPR/CCTV/NVR/etc. | **POST** `/api/devices` with `name`, `lat`, `lng`, `stream_url`, `source_type` (`mjpeg` or `hls`), and optional `device_type`, `vendor`. |
|
||
| Edit or delete a device | **PATCH** or **DELETE** `/api/devices/:id` (admin/leader). |
|
||
| Add your phone as a live feed | Use **Share live** — see [Share live](live-streaming.md). |
|