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

3.6 KiB

QFT protocol notes — v0.4.6

1. Windows → Android optical: QFT2

Active display 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

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

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

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:

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:

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.