make kestrel a tak server, so that it can send and receive pois as cots data
Some checks failed
ci/woodpecker/pr/pr Pipeline failed
Some checks failed
ci/woodpecker/pr/pr Pipeline failed
This commit is contained in:
Madison Grubb
128
docs/map-and-cameras.md
Normal file
128
docs/map-and-cameras.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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). |
|
||||
Reference in New Issue
Block a user