89 lines
2.6 KiB
Markdown
89 lines
2.6 KiB
Markdown
# QFT protocol notes — v0.4.6
|
|
|
|
## 1. Windows → Android optical: QFT2
|
|
|
|
Active display text:
|
|
|
|
```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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|