# 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). |