Files
QFT/docs/PROTOCOL.md
T
2026-08-11 11:27:40 +08:00

104 lines
3.6 KiB
Markdown

# QFT protocol notes — v0.4.6
## 1. Windows → Android optical: QFT2
Active display text:
```text
QFT2:<Base45(binary-frame)>
```
Base45 is used because its alphabet fits QR alphanumeric encoding, while Android can consume a normal ZXing `Result.text`. The receiver also keeps legacy `QFT1:<base64url(...)>` parsing for old senders.
### Binary frame
```text
magic 4 "QFT2"
version 1 2
kind 1 1=MANIFEST / 2=DATA / 3=END
session 8 u64 BE
sequence 4 u32 BE
total 4 u32 BE
payloadLen 2 u16 BE
payload N
crc32 4 u32 BE over everything before crc32
```
### MANIFEST payload
```text
fileSize 8 u64 BE
chunkSize 2 u16 BE
sha256 32
fileNameLen 2 u16 BE
fileName N UTF-8
senderLen 2 u16 BE
senderDevice N UTF-8
```
### Optical parameters in v0.4.6
- one QR per display frame;
- DATA payload: **450 B**;
- QR error correction: L;
- full 4-module quiet zone;
- Windows display target: 5~60 FPS, default 45;
- synthetic representative DATA frame: 722 text chars / QR-L v15;
- theoretical payload at 60 display FPS: 27,000 B/s ≈ 26.4 KiB/s before camera misses/replay.
Sender continuously loops `MANIFEST → DATA 0..N-1 → END`. Android deduplicates by sequence number and reconstructs once all chunks are present. No reverse ACK/network channel exists for this direction.
## 2. Android optical ROI state machine
```text
ACQUIRE
center search
occasional full frame
↓ success
LOCKED
copy Y-plane ROI only
GlobalHistogram every frame
sparse Hybrid fallback
↓ finder points
smooth ROI position/size
↓ misses
expand ROI
↓ sustained misses
REACQUIRE
```
The overlay is derived from the same ROI used by the decoder, so the green/yellow box is not decorative—it reflects the actual analysis area.
## 3. Android → Windows pairing
`QFTPAIR2` remains the active pairing format from v0.3. It contains local-only session/network metadata. Android validates the pairing endpoint as a literal local/private IPv4 and binds subsequent discovery/upload to the selected local `Network`.
Discovery order includes QR hint, UDP `QFTDISC2`, gateway/direct candidates and bounded current-subnet fallback.
## 4. Android → Windows upload
Parallel v2 flow:
```text
POST /qft/upload/init
POST /qft/upload/chunk (parallel, offset based)
POST /qft/upload/finish
```
Windows preallocates a `.qftpart`, writes chunks at explicit offsets, verifies SHA-256, then renames to the final file. Per-file worker count is capped at 8; chunk size is selected from 4/8/16 MiB by file size.
Repeated `init` requests carrying the same `X-QFT-Upload-Key` resume the matching active upload session. The response may include a `missing` chunk-index array; the client sends only those chunks. Chunk completion is recorded only after the positioned write reaches stable storage.
## 5. Windows → Android direct download
Files of at least 32 MiB use up to 8 parallel bounded range requests:
```text
GET /qft/download
Range: bytes=<start>-<end>
```
Android preallocates an app-private `.qftpart`, writes each range at its fixed offset and persists a separate completion bitmap. A reconnect or process restart downloads only missing ranges. After every range is present, Android verifies the QR-carried SHA-256 before publishing the file to `Downloads/QFT`.
The Android `WifiNetworkSpecifier` request remains registered for the entire transfer page. It is released when the user returns to the home page (or the Activity is destroyed); a replacement `Network` delivered after a brief radio loss is adopted by subsequent chunk/range retries.