# Lesavka

<p align="center">
  <img src="client/assets/icons/hicolor/1024x1024/apps/lesavka.png" alt="Lesavka icon" width="260" />
</p>

Lesavka is a control surface for lab equipment that needs to feel close at hand even when the actual machine is all the way down a flight of stairs. It pulls the important pieces into one place: the two eye feeds, input ownership, staged camera/audio devices, capture power, diagnostics, and the session log.

The point is simple: sit down at the desk, confirm the equipment side is awake, pick the devices you want, and work without guessing what the lab machine is doing.

## What It Does

- Shows the left and right eye feeds in the launcher, with breakout windows when you want more room.
- Lets you stage input and output choices before a session starts.
- Moves keyboard and pointer ownership between the operator station and the equipment side on purpose, not by accident.
- Keeps capture power and GPIO state visible to tell whether the capture devices are actually awake.
- Keeps diagnostics and logs close by so a weird media/device state is something we can prove, not hand-wave.
- Installs through repeatable client and server scripts so a reboot or reinstall does not leave mystery settings floating around.

## Install / Update

### Operator Station

```bash
cd /home/brad/Development/lesavka
git pull --ff-only
sudo LESAVKA_REF=master ./scripts/install/client.sh
```

### Equipment Side

```bash
ssh <equipment-host> 'cd /var/src/lesavka && git pull --ff-only && sudo LESAVKA_REF=master ./scripts/install/server.sh'
```

The install scripts are the trusted path. They make the expected directories, install the binaries, refresh the desktop launcher or service, and keep the config in predictable places.

## Daily Shape

1. Launch `Lesavka` from the desktop menu or run `lesavka`.
2. Refresh devices if hardware changed.
3. Pick the camera, camera quality, speaker, microphone, keyboard, and mouse you want for the next run.
4. Confirm the server chip is green before trusting the session. Yellow means the server is visible but no live relay is connected yet. Red means treat it as missing.
5. Connect the relay, watch both eyes come online, then move inputs when you are ready.
6. Use diagnostics and the session console when the bench feels wrong. The log should say what happened.

## Media Notes

- Eye capture has server-side controls for resolution, frame rate, and bitrate.
- Camera uplink quality is selected from modes the webcam actually reports and Lesavka knows how to send.
- Live queues are bounded. Stale frames should drop instead of piling up latency.
- The HDMI/UVC path is treated as real hardware, not an abstract video toy: it needs to keep moving and stay low-latency.

## Quality Gate

Lesavka has to prove the parts that work keep working.

The gate order is:

```text
style/docs -> LOC/naming -> coverage -> tests -> media reliability -> gate glue -> SonarQube -> supply chain/artifact security
```

TLDR: formatting and hygiene first, source files under the line limit, every tracked source file at 95%+ coverage, normal tests green, media tests proving frames keep moving, then the reporting/security checks.

Useful entry points:

```bash
./scripts/ci/platform_quality_gate.sh
./scripts/ci/quality_gate.sh
./scripts/ci/test_gate.sh
./scripts/ci/media_reliability_gate.sh
```

## Operational Notes

- Runtime and test environment variables are indexed in `docs/operational-env.md`.
- Gate criteria and evidence paths are documented in `docs/quality-gate.md`.
- Manual hardware checks belong in clearly marked manual scripts, not hidden in CI-only assumptions.
- If the launcher says a device path, format, or stream is wrong, fix the setup or the code until the evidence is boring.

## Versioning

Lesavka uses semver: `<major>.<minor>.<patch>`.

- Patch: bug fixes, UI polish, installer hardening, logging clarity, stability work.
- Minor: new controls, diagnostics, protocol additions, or operator-visible behavior that stays compatible when both sides are updated together.
- Major: deliberate breaking changes to protocol, install behavior, or workflow.
