Files
QFT/docs/PROTOCOL.md
T
2026-08-12 16:40:43 +08:00

5.2 KiB
Raw 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.

6. Android → Android (QFTPHONE2, v0.5.0-dev4)

The sender starts an authenticated local HTTP service and encodes only session, port, sender identity and optional dedicated-network credentials in the QR. The file queue is fetched after pairing so QR density is independent of queue size:

GET /qft/ping
GET /qft/phone/manifest
GET /qft/phone/download/<queue-index>
Range: bytes=<start>-<end>
X-QFT-Token: <one-time session>

The manifest contains a bounded ordered list of name, size, sha256 and a server-generated fixed download path. The receiver does not accept arbitrary paths from the QR or manifest: entry N must use /qft/phone/download/N.

Android prefers a 2.4 GHz WPA2 Wi-Fi Direct group-owner AP that accepts legacy Wi-Fi stations. An OEM P2P failure falls back to LocalOnlyHotspot, then literal private IPv4 endpoints on the current LAN. WPA2/WPA3 credentials are distinguished in w[2]. The receiver reuses the existing Range ledger, retries and SHA-256-before-publish behavior for every file, processing items in manifest order. Phone senders use one deterministic Range worker to avoid concurrent-read corruption in older Android document providers; desktop senders retain up to eight workers.