# MOSAIC-HF 0.1.0a1 — Alpha Operator Guide

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

---

## 1. What 0.1.0a1 Is and Is Not

### What It Is
MOSAIC-HF 0.1.0a1 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 `tools/mosaic_modem.py` and `tools/mosaic_console.py`.
- **HF Audio-Path Single-User Operation:** Single-user byte-exact packet transmission and reception through SSB transceiver sound interfaces (`tools/mosaic_hf_audio.py`).
- **HF Realtime Decoding:** Single-user realtime decoding (~0.10× wall-clock) with robust performance across simulated ITU-R F.1487 channel profiles.

### 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 Multi-User HF Under Ionospheric Fading:** Multi-user SIC convergence under correlated ionospheric fading is not yet demonstrated beyond 1–2 stations.
- **Not Direct HF SDR Radiating IQ:** Direct SDR radiation of the 12.5 Hz tone grid on HF suffers from local oscillator (LO) drift on un-disciplined SDR hardware. HF operation requires a transceiver audio path.
- **Not a Consumer Appliance:** Requires an active control operator, manual gain discipline, and preflight configuration.

---

## 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.0a1-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`)

The UHF operating path uses `tools/mosaic_modem.py` to manage SDR hardware and serve a standard KISS TCP socket (default `127.0.0.1:8001`), attached to `tools/mosaic_console.py` 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
python tools/mosaic_modem.py \
  --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
python tools/mosaic_modem.py \
  --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
python tools/mosaic_console.py --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 `tools/mosaic_hf_audio.py`.

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

```bash
python tools/mosaic_hf_audio.py devices
```

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

```bash
python tools/mosaic_hf_audio.py loopback --device <INDEX> --text "VE6SLP TEST"
```

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

```bash
python tools/mosaic_hf_audio.py 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
python tools/mosaic_hf_audio.py 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 / NO** | 1–2 stations reliable; SIC tracking under fading not demonstrated beyond two users. |
| 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/`.