# Camera & sensors

> Motion wake, face presence, tamper detection, snapshots, the MJPEG stream, camera popups and QR config import.

Kiosky can use the tablet's front camera and sensors to wake the screen, report presence to Home Assistant and send snapshots. Everything is **off by default** and processed on the device. Find the settings under **Settings, Camera & sensors**.

> **Note.** Camera features are among the candidate [Kiosky Pro](pro.md) features. While Pro is in development every feature is unlocked.

## Privacy at a glance

- Motion and face detection analyse frames on the tablet and discard them. Frames never leave the device.
- Face detection only counts faces. It never recognises anyone, and no image is stored or sent.
- Only snapshots (on request, or on motion if you enable it) leave the device, and only to your MQTT broker or to a REST client that has your API token.
- The live stream is the one feature that sends camera frames continuously, and only to a client that has your API token.
- While the camera is on, Android shows its green camera indicator.

## Camera permission

Under **Camera**, **Camera permission** shows **Granted** or an **Allow** button. It is needed for motion detection, snapshots and QR scanning. If no prompt appears, open Android settings, Apps, Kiosky, Permissions, Camera. On Device Owner tablets the permission can be granted automatically (see [Lock options](modes.md#lock-options)).

If the device has no camera, the section says so, and the camera entities are not created.

## Motion detection

Turn on **Motion detection** to analyse the front camera at low resolution.

| Setting | Default | Notes |
|---|---|---|
| Motion detection | Off | |
| Wake screen on motion | Off | Treats movement like a touch. It wakes the screen from dim, screensaver and off. |
| Snapshot on motion | Off | Publishes a photo to MQTT when motion starts, at most every 30 seconds. |
| Sensitivity | 50% | 0% needs large movement, 100% is very sensitive. |
| Analysis rate | 2 fps | 1 to 10 frames per second. |

**Live preview** lets you tune sensitivity while watching the detector: it shows **Motion** or **Still** and the percentage of the image that changed against what is needed.

Motion is reported to Home Assistant as the **Motion** binary sensor, and as `motion` in the REST and MQTT state.

## Face presence

**Face presence** reports a presence sensor to Home Assistant by counting faces in view. It uses ML Kit on the front camera, which costs roughly 3 to 6% CPU at 2 fps, so it is opt-in.

| Setting | Default | Notes |
|---|---|---|
| Face presence | Off | Creates the **Presence** binary sensor. |
| Wake screen on face | Off | Treats a face in view like a touch. |
| Detection rate | 2 fps | 1 to 4 fps. |
| Hold time | 30 s | 5 to 600 s. Presence stays on this long after the last face. |

## Tamper detection

**Tamper detection** uses the accelerometer, at low power, to flag the tablet being lifted, shaken or turned. It publishes a `device_moved` event and sets the **Tamper** binary sensor. **Sensitivity** runs from 0% (needs a real lift) to 100% (any nudge); the default is 50%.

## Snapshots

A snapshot is a JPEG of the front camera. Three ways to get one:

- In the app, **Take a test snapshot** under **Camera**.
- Send the `snapshot` command (REST, MQTT or the **Take snapshot** button in Home Assistant). The JPEG is published to `kiosk/<device_id>/camera/snapshot` and appears as the **Camera snapshot** image entity.
- `GET /api/camera/snapshot` returns a JPEG, no older than a couple of seconds, over the [REST API](rest-api.md#camera).

## Live stream

The REST server can serve the front camera as an MJPEG stream.

1. Turn on **Settings, Connections, Remote access, REST API & admin page** (the stream is served by that server).
2. Under **Camera & sensors, Live camera stream**, turn the stream on.
3. Set **Frame rate** (1 to 5 fps, default 2) and **Largest side** (160 to 1280 px, default 480). JPEG quality is 60 by default (the config accepts 30 to 90).

The camera only runs while a viewer is connected, and at most 2 viewers can connect at once. Turning the stream on is a protected setting, so it can only be changed on the tablet unless you allow remote security changes (see [Security](security.md#protected-settings)).

The app shows the exact values to use. In Home Assistant add a **Generic MJPEG camera** (the `mjpeg` integration) with:

```text
URL:            http://TABLET_IP:2323/api/camera/stream
Username:       kiosky
Password:       <your API token>
Authentication: basic
```

HA's `mjpeg` camera cannot send a Bearer header, so this one path also accepts HTTP Basic with the fixed username `kiosky` and your token as the password. A `?token=` query is deliberately not supported, because it would leak into URLs and logs.

## Camera popups

Home Assistant can pop a camera feed over the dashboard, for example when the doorbell rings. This uses the **Home Assistant** camera, not the tablet's own camera.

- Save your Home Assistant address and token under **Dashboard, Home Assistant sign-in**.
- Send the `popup` command with a `camera` entity id (or up to four), an optional `timeout` in seconds and an optional `title`:

```json
{"command": "popup", "args": {"camera": ["camera.front_door", "camera.driveway"], "timeout": 30, "title": "Doorbell"}}
```

Kiosky reads each camera from Home Assistant (an MJPEG stream, or one JPEG per second when the server does not stream), reconnecting if it drops. The popup wakes the screen and closes on its timeout, on the close button, with Back, or with `dismiss_popup`. See [Home Assistant integration](home-assistant.md#show-the-door-camera-when-someone-is-at-the-door) for an automation.

## Import settings with a QR code

Under **Camera**, **Scan QR to import config** reads a QR code that contains either a Kiosky config as JSON or a link to one (`http` or `https`, no username in the link). Nothing is applied until you review a list of changes and tap **Apply**. A partial config only changes the fields it contains, and everything else keeps its value.

## Troubleshooting

If the camera will not start, another app may be using it, or the permission is missing. See [Troubleshooting](troubleshooting.md#camera-is-busy-or-unavailable).