Files
2026-08-13 09:15:11 +08:00

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

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

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 10+ first creates a WPA2 Wi-Fi Direct group-owner AP with automatic band selection, normally allowing a 5 GHz link. If no authenticated peer arrives in 12 seconds, the sender recreates the group on 2.4 GHz with the exact same SSID and passphrase, so an older receiver's pending scan continues without a new QR. 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.