# MOSAIC-HF 0.1.0a7 — Alpha Operator Guide

This guide describes how to install, configure, and operate the MOSAIC-HF 0.1.0a7 alpha release. It provides operational instructions for browser-controlled UHF SDR QSOs, adaptive mixed-rate operation, keyboard QSOs, and single-user HF transceiver audio-path testing.

---

## 1. What 0.1.0a7 Is and Is Not

### What It Is
MOSAIC-HF 0.1.0a7 is an alpha software release for licensed amateur radio experimenters. It provides:
- **UHF Multi-User On-Air Operation:** Up to 12 asynchronous stations decoded simultaneously on a 70 cm shared channel (431.2 MHz lab context) using successive interference cancellation (SIC).
- **UHF Live Keyboard QSO:** Bi-directional live keyboard exchanges over an SDR air path using `mosaic-modem` and `mosaic-console`.
- **Realtime Operator Console:** A local browser workspace with live spectrum and waterfall, front-end IQ diagnostics, decoded stations, guided QSO controls, transcript, receiver health, and explicit fail-closed TX control.
- **HF Audio-Path Single-User Operation:** Single-user byte-exact packet transmission and reception through SSB transceiver sound interfaces (`mosaic-hf-audio`).
- **HF Realtime Decoding:** Single-user realtime decoding (~0.10× wall-clock) with robust performance across simulated ITU-R F.1487 channel profiles.
- **Adaptive Mixed-Rate Operation:** Version-2 Basic/middle/fast profile banks, per-QSO Auto/forced rate control, conservative promotion/fallback, and mixed-profile CRC-gated SIC.
- **Three-Radio Mixed-Rate Evidence:** UHF Basic/Fast/Turbo and HF Basic/Chat/Fast-over-UHF each recover 3/3 CRC-valid at 100% measured active-span occupancy.

### What It Is Not
- **Not an On-Air Two-Way HF QSO System:** No confirmed two-way on-air HF QSO has been achieved or claimed.
- **Not Fully Solved Multi-User HF Under Ionospheric Fading:** Simulation with the `hf-congested` stack now recovers most stations under Watterson-style fade (e.g. 6-user mean ≈5.8/6; 8-user mean 6.5/8 across seeds). Hard pure-MAI seeds remain; uncoordinated TX access jitter and optional time-diversity repeats are the alpha mitigations. Not an on-air HF multi-user claim.
- **Not a Direct-HF RF Front End:** The narrow HF waveform now decodes CRC-valid over cabled and radiated UHF SDR IQ paths with local timing/CFO/drift refinement. This proves the modem and free-running SDR conversion path at 431.200 MHz; it is not an HF-band propagation or transceiver claim. HF operation still uses the transceiver audio path.
- **Not a Consumer Appliance:** Requires an active control operator, manual gain discipline, and preflight configuration.

### Lab multipath (UHF cabled and radiated)
Composite BladeRF TX with a static two-path FIR (2 ms, second-path gain 0.7) recovered both users CRC-valid under the HF congested decode stack on the fixed-pad cabled path and again on the radiated antenna path at 431.200 MHz. See `docs/ALPHA-CAPABILITY-MATRIX.md` and `run-artifacts/hf-multiuser/uhf-multipath-*-2user-evidence.json`.

---

## 2. Installation

### Virtual Environment Setup
Set up a clean Python virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

### Installation Options
Install directly from source or from a pre-built wheel:

```bash
# Option A: Install from source checkout
python -m pip install .

# Option B: Install with optional soundcard audio support
python -m pip install ".[audio]"
# or: python -m pip install sounddevice

# Option C: Install from built wheel (dist/ or site/downloads/)
python -m pip install site/downloads/mosaic_hf-0.1.0a7-py3-none-any.whl
```

### Verification
Confirm entry point availability:

```bash
python -c "import mosaic_hf; print('MOSAIC-HF ready')"
mosaic-hf --help
mosaic-hf-node --help
```

---

## 3. UHF Operating Path (`mosaic-modem` + `mosaic-console`)

Before connecting hardware, run `mosaic-modem demo`. It opens the complete
operator console with simulated spectrum and traffic, plus a KISS TCP socket at
`127.0.0.1:8001`. Practice mode cannot open a radio or transmit RF. Use it to
complete CQ, station selection, open, exchange, 73, close, and TX-inhibit
actions. `mosaic-console --port 8001` attaches the packaged keyboard client.

The UHF operating path uses `mosaic-modem` to manage SDR hardware and serve a standard KISS TCP socket (default `127.0.0.1:8001`), attached to `mosaic-console` for keyboard exchanges.

### Operational Context & Requirements
- **FPGA Bitstream Pinning:** On bladeRF hardware, `--execute` strictly requires `--fpga hostedx115-latest.rbf`. Preflight verifies the bitstream SHA-256 digest and reported version `0.16.0` before radiating.
- **431.2 MHz Lab Frequency:** Standard test tuning uses `--frequency-hz 431200000`. The audio spectrum sits 100 kHz above the LO, occupying `431.3002` to `431.3387 MHz` USB in the `MOSAIC_UHF` profile.
- **Power Discipline:** Keep output power modest (`txvga2_db` ≤ 10 dB for lab air paths) to prevent front-end saturation and preserve multi-user separation.

### Step 1: Dry-Run Preflight (Prepare-Only)
Verify configuration and KISS socket binding without keying transmitters:

```bash
mosaic-modem \
  --callsign VE6SLP \
  --peer VA6GA \
  --profile uhf-live \
  --frequency-hz 431200000 \
  --listen-port 8001 \
  --fpga hostedx115-latest.rbf
```

### Step 2: Live Modem Execution
`--execute` owns the radios for **receive**. Transmit stays fail-closed until
you arm it with `/tx on` (operator stdin), **Enable TX** in the web panel, or
`--enable-tx` at start-up. Keep `txvga2` at or below 10 dB on this lab bench.
Prefer `--profile uhf-live` for continuous demod keep-up (same UHF waveform,
tighter CFO search).

```bash
mosaic-modem \
  --callsign VE6SLP --ssid 1 \
  --peer VA6GA-2 \
  --radio bladerf-hackrf \
  --profile uhf-live \
  --frequency-hz 431200000 \
  --listen-port 8001 \
  --fpga hostedx115-latest.rbf \
  --txvga2-db 10 \
  --execute --ui-port 8088 --human-events --status-interval-s 0
```

Open `http://127.0.0.1:8088/` for the radio-engineer panel (transcript, TX
inhibit, receiver health). Use `--operator-stdin` if you prefer the text console.

Alternate: attach a separate KISS console instead of `--operator-stdin`:

```bash
mosaic-console --port 8001
```

### Step 3: Hold a keyboard QSO
With `--operator-stdin`:

```text
/help
/to VA6GA-2
/tx on
CQ CQ DE VE6SLP-1
VA6GA-2> QSL 599 K
/tx off
```

Received traffic prints as human lines when `--human-events` is set. See
`docs/OPERATOR-QUICKSTART.md` for the three-radio lab recipe (bladeRF + HackRF
+ B210).

---

## 4. HF Audio Path (`mosaic-hf-audio`)

HF operation uses an SSB transceiver sound interface (e.g., Scarlett, RigBlaster, Signalink) via `mosaic-hf-audio`.

### Enumerate Sound Devices
Find the hardware device index:

```bash
mosaic-hf-audio devices
```

### Continuous Browser and KISS Station

Run the normal operator console and KISS TCP service through the transceiver
sound interface:

```bash
mosaic-hf-audio \
  --callsign VE6SLP --ssid 1 \
  --ptt-port /dev/ttyUSB0 --ptt-line rts \
  serve --peer VA6GA-2 \
  --input-device <INDEX> --output-device <INDEX>
```

Receive starts immediately. The browser is served on `127.0.0.1:8088` and
KISS TCP on `127.0.0.1:8001`. PTT and audio output remain inhibited until the
operator arms TX. Repeat `--peer` for each expected station.

### Converter Loopback Test
Test local sound card converters through a physical audio loopback:

```bash
mosaic-hf-audio loopback --device <INDEX> --text "VE6SLP TEST"
```

### Transmit Audio to Rig
Transmit a single packet to the rig audio input:

```bash
mosaic-hf-audio transmit --output-device <INDEX> --text "CQ DE VE6SLP"
```

*Drive Level Discipline:* Amplitude defaults to 0.25 (`--amplitude 0.25`) to prevent SSB ALC splatter. Use serial keying (`--ptt-port /dev/ttyUSB0 --ptt-line rts`) when hardware PTT is required.

### Receive Audio from Rig
Listen for incoming MOSAIC-HF bursts:

```bash
mosaic-hf-audio receive --input-device <INDEX> --seconds 30
```

---

## 5. Safety, Legal, and Operating Rules

- **Licensed Control Operators Only:** Operation is restricted to licensed radio amateurs complying with local band plans, power ceilings, and station identification requirements.
- **Fail-Closed Transmit Safety:** Dry-run is the default. `--execute` enables live receive only; transmit remains inhibited until `/tx on` or `--enable-tx`.
- **Hardware Protection:** Never connect transmit ports directly to receive ports without verified RF attenuation (e.g., 50 dB pad rated for transmit power).
- **Operator Presence:** A human control operator must remain present to inhibit transmission immediately if required.

---

## 6. Known Capabilities and Limitations

Claims in this release match `docs/ALPHA-CAPABILITY-MATRIX.md` exactly:

| Capability | Status | Operational Notes |
|---|---|---|
| UHF Multi-User On-Air (12 Stations) | **YES** | Demonstrated on 70 cm (431.2 MHz) with independent transmitters. |
| UHF Live Keyboard QSO | **YES** | Live bi-directional keyboard exchange over 70 cm SDR path. |
| HF Audio Path (Single-User) | **YES** | Byte-exact end-to-end through sound interfaces. |
| HF Realtime Decode (Single-User) | **YES** | Decodes at ~0.10× wall-clock time on reference hardware. |
| HF ITU F.1487 Single-User | **YES** | Verified across simulated ITU channel profiles. |
| HF Multi-User Under Watterson Fading | **LIMITED (sim improved)** | Simulation only: `hf-congested` + multi-order known-payload residual rebuild recovers 4/4, 6-user mean 5.83/6 (full 83%), 8-user mean 6.50/8 (full 50% over 6 seeds). Multi-tap alone ~2.8/6. Not on-air HF. See `hf-8user-rebuild-6seeds.json`. |
| HF Direct SDR Radiate (IQ Path) | **PARTIAL** | Burst acquisition succeeds, but over-air IQ decode unconfirmed due to LO drift. |
| On-Air Two-Way HF Contact | **NO** | No two-way HF on-air contact has been conducted or claimed. |

---

## 7. Reporting Results and Retaining Evidence

To submit experimental results for project verification:
1. **Retain Manifests:** Save all JSON status and run manifests generated during operation.
2. **Compute SHA-256 Hashes:** Include SHA-256 checksums for any retained raw IQ or audio capture files (`.cs8`, `.cf32`, `.sigmf-data`):
   ```bash
   sha256sum run-artifacts/my-run/raw_rx.cs8
   ```
3. **Record Operating Conditions:** Document hardware models, serials, firmware/FPGA versions, gain settings, center frequencies, and observed power levels (dBFS).

## Fresh lab QSO recipe

See [`docs/ALPHA-UHF-QSO-RECIPE.md`](ALPHA-UHF-QSO-RECIPE.md) for the bidirectional on-air command pair retained under `run-artifacts/alpha-uhf-qso/`.