5.0 KiB
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-dev1)
The sender starts an authenticated local HTTP service and encodes only session, port, sender identity and optional LocalOnlyHotspot 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 8+ prefers a system LocalOnlyHotspot. Android 7, or a hotspot failure,
falls back to literal private IPv4 endpoints on the current LAN. WPA2/WPA3
credentials are distinguished in w[2]. The receiver then reuses the existing
parallel Range ledger, retries and SHA-256-before-publish behavior for every
file, processing items in manifest order.