Files
QFT/docs/PROTOCOL.md
T
zhy a960ad91d8 合并 0.4.7 双向并发传输封版
# Conflicts:
#	README.md
#	android/app/src/main/java/com/qft/optical/DownloadClient.kt
#	android/app/src/main/java/com/qft/optical/UploadClient.kt
#	docs/PROTOCOL.md
#	windows/src/sender.rs
2026-08-11 14:27:30 +08:00

4.0 KiB
Raw Permalink Blame History

QFT protocol notes — v0.4.7

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.7

  • 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)

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. Uploads target 8 workers per file (bounded by the usable chunks and device capacity); the requested chunk size is derived from the file size and clamped to 64 KiB–16 MiB. Repeated init requests carrying the same X-QFT-Upload-Key resume the matching active upload session; repeated chunk and finish requests are idempotent so a lost response can be retried safely. Chunk completion is recorded only after the positioned write reaches stable storage.

5. Windows → Android download

The same QFTPAIR2 local session can declare the download direction. Android discovers and verifies the Windows sender, then downloads GET /qft/download with exact single-range requests:

Range: bytes=<start>-<end>

The sender returns 206 Partial Content, the matching Content-Range, and the exact requested body length. Android splits the file toward 8 workers with 64 KiB–16 MiB chunks, stores each completed chunk in a .qftpart.map ledger, and resumes only missing chunks after a reconnect. Each range retries with the currently available Network; the complete partial file must pass SHA-256 before it is published to Downloads/QFT.

For both direct-transfer directions, the Windows listener may accept connections non-blockingly for shutdown responsiveness, but each accepted file socket is switched to blocking I/O with explicit timeouts before reading or writing request bodies. This prevents WSAEWOULDBLOCK (10035) from turning an in-progress parallel transfer into an HTTP 500 failure.