Reverse-Engineered thermal master p3: complete USB protocol, register map, sub-LSB lock-in & compression

0. Which Mode Should I Use? (Visualizing vs. Collecting Raw Signal)

Everything the camera and app do boils down to two workflows: (1) Visualizing live thermal video, or (2) Collecting the highest-quality raw sensor signal over GET /stream.raw.z to process in Python on the host. Crucially, GET /stream.raw.z (and /stream.raw) always streams the 256×192 uint16 plane and 512-word InfoLine straight from USB before any phone-side processing—only the four camera hardware registers (nuct_bypass, TNR, SNR, auto_ffc) change the raw signal.

# Switch presets remotely over Tailscale or LAN (pass Authorization: Bearer $SPACESHEEP_API_KEY):
# 1. Live visualization (default factory settings: 1/64 K, NR 50/50, Auto-FFC ON)
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://<phone-ip>:8080/api/control?action=preset&name=visualize"

# 2. Raw 14-bit NUC signal collection (-38.62 mK/LSB, NR 0/0, Auto-FFC OFF) + trigger one clean shutter before recording
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://<phone-ip>:8080/api/control?action=preset&name=raw"
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://<phone-ip>:8080/api/control?action=shutter"

# 3. Raw calibrated 1/64 K signal collection (62.5 mK/LSB, NR 0/0, Auto-FFC OFF)
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://<phone-ip>:8080/api/control?action=preset&name=raw_calibrated"

Summary Metrics & The 11 Hard-Won Reverse-Engineering Lessons

Every major obstacle below cost hours of binary disassembly, USB packet sniffing, or live hardware debugging. Follow these 11 rules verbatim to avoid every trap:

1. Trap 1 — Why standard UVC / Camera2 / WebRTC getUserMedia completely fails Although older InfiRay P2 modules use UVC (bInterfaceClass = 0x0E), the Thermal Master P3 (VID=0x3474, PID=0x45A2) declares a proprietary vendor class (bInterfaceClass = 0xFF, bInterfaceSubClass = 0xF0) with raw Bulk IN endpoint 0x81. Neither Linux uvcvideo, Android Camera2, nor Chrome's navigator.mediaDevices.getUserMedia enumerates it. You must open it directly via UsbManager.openDevice() / libusb.
   USB Class 0xFF
2. Trap 2 — AC020 18-Byte CRC16-CCITT protocol vs. legacy AC010 8-byte commands Sending legacy InfiRay P2 / AC010 8-byte vendor packets is silently ignored or rejected. The P3 runs the Gen-2 AC020 protocol (libircmd020.so) over EP0 (bmRequestType=0x41, bRequest=0x20): every command is an 18-byte header where bytes [0..1] are Big-Endian cmdType, bytes [2..15] have Little-Endian fields, and bytes [16..17] carry a Little-Endian CRC16-CCITT (XMODEM, poly=0x1021, init=0x0000) computed over bytes [0..15].
   CRC16-XMODEM
3. Trap 3 — The 6-Step Handshake & why calling setInterface twice kills the 2s sensor timer The P3 will not emit bulk frames unless you execute an exact 6-step sequence: (1) send CMD_START_STREAM (0x012F/0x0081), (2) sleep(1000ms), (3) setInterface(iface=1, alt=1) + vendor FIFO reset 0x40/0xEE (wValue=0, wIndex=1), (4) sleep(2000ms) while the ASIC boots its VSYNC pipeline, (5) 150ms flush read on EP 0x81, and (6) final CMD_START_STREAM. Crucial trap: if you call setInterface(alt=1) again at Step 6, the USB bridge resets its 2-second sensor timer and bulk reads time out forever!
   2s Timer Trap
4. Trap 4 — USB Hub Transaction Translator (TT) recovery via 0x40/0xEE without setInterface When running through a USB-C PD hub (e.g. Anker 332), occasional cable micro-bumps or PD negotiations cause bulkTransfer timeouts. After 2 consecutive 750ms bulk timeouts, recover in-place in <60 ms by sending controlTransfer(0x40, 0xEE, 0, 1) + CMD_START_STREAM + parser.reset() without calling setInterface(alt=1).
   Hub Recovery
5. Trap 5 — Powered USB hub reconnect leaves P3 in streaming state with wedged EP0 When unplugging and replugging the P3 into a powered USB-C hub, VBUS never drops, so the P3 stays mid-stream while its EP0 state machine rejects initial register reads (CMD_READ_NAME returns empty). Fix: detect empty initial read and invoke Android's hidden UsbDeviceConnection.resetDevice() via Java reflection, sleep 600 ms, re-claim interfaces 0 and 1, and retry.
   EP0 Wedge Fix
6. Trap 6 — 10 ms EP0 command spacing + 0xC1/0x22 BUSY polling + stale SRAM buffer trap Back-to-back EP0 commands faster than 10 ms overflow the RT-Thread command queue; enforce a 10ms minimum gap and poll 0xC1/0x22 until bit 0 (BUSY = 0x01) clears. Furthermore, if 0xC1/0x22 returns 0x04 (rejected opcode), firmware does not clear its EP0 SRAM buffer—a subsequent 0xC1/0x21 read returns stale bytes from the previous valid command! Never probe class 0x0104 (raw I2C master read), which hangs the internal sensor I2C bus until power cycle.
   I2C & SRAM Trap
7. Trap 7 — Physical bump sticks mechanical shutter closed or corrupts FFC baseline A physical tap during FFC actuation can leave the mechanical shutter blade stuck closed or corrupt the flat-field baseline (spanC < 0.30°C and stdDevC < 0.05°C, or fpaTempC > 34.5°C with stdDevC < 0.35°C). Auto-detecting this condition for 75 consecutive frames (3.0s) and firing CMD_SHUTTER (0x0136/0x0043) with a 20s cooldown self-heals the image hands-free.
   Auto-Shutter Heal
8. Trap 8 — 204,800-byte NUC transition frames vs. 197,656-byte normal wire frames Normal frames are exactly 197,656 bytes (12B start marker + 197,632B payload + 12B end marker). However, every time the shutter actuates (0x0136/0x0043), the camera emits a 204,800-byte (200 KiB) bulk transfer containing a 9,204-byte partial aborted frame before restarting the new frame. A naive fixed-size reader permanently loses byte alignment; our bounded resynchronizing parser checks endSync == startSync + 2 and startCnt1 == endCnt1 to discard the 9,204-byte fragment with zero dropped sync.
   Sync Parser
9. Trap 9 — Why bits 0..1 of every temperature word are always 0 (62.5 mK quantum) & how nuct_bypass=1 unlocks -38.62 mK/LSB Although the wire container is 1/64 K (15.625 mK), 100.000% of pixels in default mode satisfy raw % 4 == 0 (62.50 mK step). Disassembly of remap_temp in libadvirtempac020.so revealed why: the ISP computes NUC_ktbt >> 1 (throwing away 1 bit!) to index an 8,192-entry 1/16 K LUT and shifts the result left by 2 (<< 2). Sending adv_bypass_nuct_set(1) (0x0126/0x0048, reg=1) bypasses both >> 1 and the LUT, outputting un-halved 14-bit NUC counts (raw_u16 = nuc14 << 2) at -38.62 mK / LSB (1.7× finer hardware granularity).
   14-Bit NUC Unlock
10. Trap 10 — Why naive delta compression fails & how Closed-Loop DPCM + >> 2 + ZigZag + Byte-Shuffle hits 19.7×–325× In two's complement int16, a tiny -1 noise fluctuation is 0xFFFF while +1 is 0x0001, flipping all 8 bits of the MSB on 50% of pixels and destroying zlib compression. By (1) stripping the 2 zero LSB padding bits (v14 = raw >> 2), (2) running a closed-loop DPCM predictor with optional deadband k, (3) ZigZag-folding signs ((d << 1) ^ (d >> 31)) so the entire 49,152-byte high-byte plane becomes 100% zeros, and (4) grouping low bytes and high bytes into separate contiguous planes before zlib, lossless streaming drops from 39.54 Mb/s to 2.00 Mb/s (19.7×) and deadband-3 reaches 0.12 Mb/s (325.1×) with zero drift.
    19.7×–325× Codec
11. Trap 11 — Solving the 0 FPS headless Android WebView WebRTC bug with MediaStreamTrackGenerator When publishing a 30 FPS WebRTC stream from an Android foreground service using an offscreen WebView (no SurfaceFlinger window token), Chromium's HTML5 canvas compositor never flushes canvas.captureStream(30) (outbound-rtp.framesSent stays 0). Using WebCodecs Insertable Streams (new MediaStreamTrackGenerator({ kind: "video" })) driven by an unthrottled 33ms Web Worker calling writer.write(new VideoFrame(canvas, { timestamp })) bypasses the compositor completely and sustains 30.2–30.6 FPS at 1.8 Mbps RTP.
    30 FPS WebRTC

1. Hardware Identity, Optics & Serial Number (SNInfo) Decoding

1.1 Serial Number (SNInfo) Decoding Table (P3025043DG040200256)

1.2 Live basic_device_info_get (0x0101 / 0x0081) Sub-IDs 0..20

Every sub-ID below was queried live on SN: P3025043DG040200256 via GET /api/probe while streaming 25 FPS video. When the 10ms artificial safety delay is omitted, individual EP0 register reads complete in 0.54–1.34 ms (9.5–12.1 ms with 10ms pacing enforced; sub-ID 0x0D takes 177.26 ms because firmware reads the SPI flash package header):

2. The 18-Byte CRC16-CCITT Vendor Control Protocol (libircmd020.so)

2.1 Exact 18-Byte Command Header Layout

All register reads and writes use an 18-byte command packet sent over EP0 with bmRequestType = 0x41 (Host-to-Interface, Vendor), bRequest = 0x20, wValue = 0x0000, wIndex = 0x0000. Note the mixed endianness: cmdType at bytes [0..1] is Big-Endian, while param, register, respLen, and crc16 are Little-Endian:

Byte:   0      1      2      3      4      5     6..11    12     13     14     15     16     17
     +------+------+------+------+------+------+--------+------+------+------+------+------+------+
     | cmdType BE  |  param LE   | register LE | 0x00*6 | respLen LE  |0x00*2| CRC16-CCITT (LE)   |
     | [0]  | [1]  | [2]  | [3]  | [4]  | [5]  | [6..11]| [12] | [13] |14..15| [16] | [17]        |
     +------+------+------+------+------+------+--------+------+------+------+------+------+------+
     |<----------------- CRC16-CCITT (poly=0x1021, init=0x0000) over bytes 0..15 ---------------->|

2.2 The 4-Step EP0 Control Transfer Sequence & UART Console Log Extraction

// Kotlin: Exact 18-byte command builder + CRC16-CCITT (XMODEM)
fun crc16Ccitt(data: ByteArray, length: Int = 16): Int {
    var crc = 0x0000
    for (i in 0 until length) {
        crc = crc xor ((data[i].toInt() and 0xFF) shl 8)
        for (bit in 0 until 8) {
            crc = if ((crc and 0x8000) != 0) ((crc shl 1) xor 0x1021) and 0xFFFF
                  else (crc shl 1) and 0xFFFF
        }
    }
    return crc
}

fun buildCommand(cmdType: Int, param: Int, register: Int = 0, respLen: Int = 0): ByteArray {
    val b = ByteArray(18)
    b[0] = ((cmdType ushr 8) and 0xFF).toByte() // Big-Endian
    b[1] = (cmdType and 0xFF).toByte()
    b[2] = (param and 0xFF).toByte()            // Little-Endian
    b[3] = ((param ushr 8) and 0xFF).toByte()
    b[4] = (register and 0xFF).toByte()         // Little-Endian
    b[5] = ((register ushr 8) and 0xFF).toByte()
    b[12] = (respLen and 0xFF).toByte()         // Little-Endian
    b[13] = ((respLen ushr 8) and 0xFF).toByte()
    val crc = crc16Ccitt(b, 16)
    b[16] = (crc and 0xFF).toByte()             // Little-Endian CRC16
    b[17] = ((crc ushr 8) and 0xFF).toByte()
    return b
}

2.3 Complete Reverse-Engineered Register Command Table (libircmd020.so)

3. Exact 6-Step Stream Handshake & USB Hub Self-Healing Architecture

3.1 The Mandatory 6-Step Stream Start Sequence

1. Initial Start CommandClaim Interface 0 (ctrl) and Interface 1 (alt=0). Read identity registers, then send CMD_START_STREAM (0x012F/0x0081, respLen=1).
2. Wait 1,000 msMandatory Thread.sleep(1000) before switching the streaming interface alternate setting.
3. Altsetting 1 + 0xEE FIFO ResetClaim Interface 1 (alt=1), call setInterface(iface1_alt1), and send vendor control controlTransfer(0x40, 0xEE, 0, 1, null, 0, 1000).
4. Wait 2,000 msMandatory Thread.sleep(2000) while the P3 ASIC initializes its VSYNC frame generator and bulk DMA engine.
5. 150 ms Async Flush ReadPerform one throwaway bulkTransfer(epIn0x81, flushBuf, 16384, 150) to drain any power-on FIFO garbage.
6. Final Start Command (No setInterface!)Send CMD_START_STREAM (0x012F/0x0081, respLen=1) one final time. Never call setInterface here or the 2s timer resets!

// Copy-Pasteable Kotlin Handshake (from P3UsbDriver.kt):
// Step 1: Initial start_stream command
sendCommandAndReadResponse(P3Protocol.CMD_START_STREAM, 1)

// Step 2: Mandatory 1000ms wait before switching interface altsetting
Thread.sleep(1000)

// Step 3: Enable streaming interface (interface 1, altsetting 1) + 0xEE vendor FIFO reset
synchronized(controlLock) {
    conn.claimInterface(foundActive, true)
    conn.setInterface(foundActive)
    conn.controlTransfer(0x40, 0xEE, 0, 1, null, 0, 1000)
}

// Step 4: Mandatory 2000ms wait for sensor stream ready
Thread.sleep(2000)

// Step 5: Async flush read
val flushBuf = ByteArray(16384)
conn.bulkTransfer(foundEpIn, flushBuf, flushBuf.size, 150)

// Step 6: Final start_stream command (do NOT re-call setInterface here!)
sendCommandAndReadResponse(P3Protocol.CMD_START_STREAM, 1)

3.2 The 4 USB Hub Failure Modes & Self-Healing Recipes

4. Bulk Frame Wire Format (197,656 B) & Resynchronizing Parser

4.1 Exact Dual-Plane Wire Layout (197,656 Bytes @ 25.00 Hz)

Every 40.00 ms, the P3 transmits one 197,656-byte frame over EP 0x81 IN (arriving as 12.064 × 16,384-byte bulk reads at 4.94 MB/s):

+-----------------------------------------------------------------------+ Byte 0
| 12-Byte Start Marker:                                                 |
|   [0]      = 0x0C (marker length = 12 bytes)                          |
|   [1]      = 0x8C (even frame) or 0x8D (odd frame)                    |
|   [2..5]   = startCnt1 (uint32 LE, hardware clock stamped at VSYNC)   |
|   [6..9]   = startCnt2 (uint32 LE, hardware clock stamped at DMA)     |
|   [10..11] = startCnt3 (uint16 LE, 1.000 kHz ms clock mod 2048)       |
+-----------------------------------------------------------------------+ Byte 12 (Payload Offset 0)
| Plane 0: Rows 0..191 — 8-Bit Hardware AGC IR Plane (98,304 Bytes)     |
|   256 x 192 pixels x 2 bytes/pixel (YUYV):                            |
|   • Even byte (low): 8-bit hardware AGC display luminance (0..253)    |
|   • Odd byte (high): Constant 0x80 (128 neutral chroma)               |
+-----------------------------------------------------------------------+ Byte 98,316 (Payload Offset 98,304)
| Plane 1: Rows 192..193 — Embedded InfoLine Telemetry (1,024 Bytes)    |
|   512 x uint16 LE words (2 rows x 256 words):                         |
|   • Vtemp raw 14-bit NTC ADC (Word 65), frameCount (Word 64 & 180)    |
|   • Hardware ISP min/max (1/64 K) & pixel coordinates (Bytes 140..152)|
|   • 14-bit (1/16 K) Y14 scene min/max/mean statistics (Words 165..179)|
+-----------------------------------------------------------------------+ Byte 99,340 (Payload Offset 99,328)
| Plane 2: Rows 194..385 — 16-Bit Thermal / NUC Plane (98,304 Bytes)    |
|   256 x 192 pixels x 2 bytes/pixel (uint16 LE):                       |
|   • nuct_bypass=0: Calibrated 1/64 K (T_C = raw / 64.0 - 273.15)      |
|   • nuct_bypass=1: Un-halved 14-bit NUC << 2 (-38.62 mK / NUC LSB)    |
+-----------------------------------------------------------------------+ Byte 197,644 (Payload Offset 197,632)
| 12-Byte End Marker:                                                   |
|   [0]      = 0x0C (marker length = 12 bytes)                          |
|   [1]      = 0x8E (even frame) or 0x8F (odd frame) [= startSync + 2]  |
|   [2..5]   = endCnt1 (uint32 LE, MUST equal startCnt1!)               |
|   [6..9]   = endCnt2 (uint32 LE, hardware clock at frame end)         |
|   [10..11] = endCnt3 (uint16 LE, 1.000 kHz clock mod 2048, +40/frame) |
+-----------------------------------------------------------------------+ Byte 197,656

4.2 Hardware Clock Frequencies & Exact Drop Detection

• 1.000 kHz Millisecond Frame Clock (cnt3): endCnt3 is an exact 1.000 kHz (1.00 ms tick) counter wrapping modulo 2048 (0..2047). Because the sensor runs at 25.00 Hz (40.00 ms period), endCnt3 increments by +40 (mod 2048) every frame. Checking gap = (endCnt3 - ((lastEndCnt3 + 40) % 2048) + 2048) % 2048 gives hardware-exact dropped-frame detection (droppedFrames += gap / 40).
• ASIC System & Timer Clocks (cnt1, cnt2): The P3 ASIC derives its timestamp counters from its 240.0 MHz master system clock (9,592,704 master cycles per 39.970 ms frame period = 25.019 Hz with a ÷ 16 prescaler to 15.000 MHz = 599,852 ticks/frame in cnt1/cnt2, where startCnt2 - startCnt1 = 7,933 ticks = 528.9 µs DMA header setup delay). Crucially, endCnt1 == startCnt1 on every valid frame.

4.3 Why 204,800-Byte NUC Transition Frames Occur & Bounded Resynchronization

When a manual or automatic shutter FFC (0x0136/0x0043) executes, the ASIC aborts the current frame after 9,204 bytes and immediately starts a new frame inside a single 204,800-byte (200 KiB) bulk transfer (7,144 bytes longer than 197,656). P3FrameParser.feedAndPopAll (in P3Protocol.kt) handles this seamlessly without losing stream lock:

1. Scan buf from searchOffset for a candidate start marker: buf[i] == 0x0C and buf[i+1] in {0x8C, 0x8D}.
2. Wait until at least WIRE_SIZE_P3 (197,656) bytes are buffered starting at markerIdx.
3. Inspect the candidate End Marker at endMarkerOffset = markerIdx + 12 + 197,632: verify that buf[endMarkerOffset] == 0x0C, endSync == startSync + 2 (0x8C -> 0x8E or 0x8D -> 0x8F), and endCnt1 == startCnt1.
4. On the 204,800-byte NUC transition packet, the aborted 9,204-byte prefix fails the endMarkerOffset validation check (corruptCandidates++), so searchOffset advances by 1 byte, finds the true new frame's 0x0C 0x8C/0x8D marker at offset +9,204, and pops the complete valid frame with zero frame drops!

5. Complete 1,024-Byte InfoLine Memory Map (Rows 192–193)

Rows 192..193 (payload bytes 98,304..99,327, 512 × uint16 LE words) carry real-time hardware ISP telemetry in every frame with zero EP0 polling overhead. Cross-referencing live 100-frame captures against com.energy.ac020library.IrcamEngine.getInfoLineBean([B) reveals a critical alignment trap at byte 140 (frameInfoEn is a 1-byte boolean, shifting the 6 global min/max fields to odd byte offsets 141..152!):

6. Radiometric Pipeline, Calibration Binary & HIGH_PRECISION Sub-LSB Mode

6.1 In-Camera ISP Pipeline & Why Bits 0..1 Are Always Zero (62.50 mK Step)

Disassembly of ktbt_correct_process (0x30d68) and remap_temp (0x27e64) in libadvirtempac020.so revealed the exact fixed-point pipeline running inside the P3 ISP:

Raw 14-Bit Bolometer ADC
   │
   ▼  (Per-pixel shutter OOC / B flat-field offset + factory gain correction)
NUC_raw (14-bit unsigned: 0..16383, where -1 LSB = +38.62 mK hotter)
   │
   ▼  Stage 1: FPA Thermistor Drift Compensation (ktbt_correct_process)
   │  Using Vtemp (InfoLine Word 65 = 8469) & 0x0126/0x0081 (K_temp=-13696, B_temp=11464, Addr_CA=2330):
   │    idx0 = clamp(((Vtemp * K_temp + 8192) >> 14) + B_temp, 0, 4095)
   │    idx  = clamp(idx0 - Address_CA - 1, 0, 1200)
   │    NUC_ktbt = clamp(((NUC_raw * K_T[idx] + 8192) >> 14) + B_T[idx], 0, 16383)
   │
   ├──► If adv_bypass_nuct_set(1) [0x0126 / 0x0048, reg=1]:
   │       Emits raw_u16 = (NUC_ktbt << 2) directly!
   │       • Preserves all 14 bits (0..16383) with ZERO LUT rounding!
   │       • Sensitivity: -38.62 mK / LSB (25.9 LSBs / °C — 1.7x finer!)
   │
   ▼  If adv_bypass_nuct_set(0) [Default STREAMING Mode]:
   │    1. Right-shifts by 1 bit: lut_idx = (NUC_ktbt >> 1)  [0..8191, discards bit 0!]
   │    2. Indexes 8,192-entry NUC-T table in 1/16 K (62.50 mK) units: T_Y14 = NUC_T[lut_idx]
   │    3. Left-shifts by 2 bits into 1/64 K container: raw_u16 = (T_Y14 << 2)
   ▼
Wire Plane 2 (raw_u16 % 4 == 0 for 100% of pixels; T_C = raw_u16 / 64.0 - 273.15)

6.2 Factory Calibration Structures & Stefan-Boltzmann T⁴ Correction

• 44,536-Byte Factory Radiometric Calibration Block (in SPI Flash & libadvirtempac020.so): Consists of header metadata + K_T[1201] (uint16 LE Q14 FPA drift slope array, 2,402 B), B_T[1201] (int16 LE FPA drift offset array, 2,402 B), and NUC_T[8192] (uint16 LE lookup table mapping NUC >> 1 to 1/16 K temperatures, 16,384 B, plus Low-Gain tables).
• 16,384-Byte Optical / Atmospheric Transmittance LUT (assets/rs300_tau/V303_P3_4.3mm_H.bin & L.bin): Loaded by the host when PID == 0x45A2 to look up transmittance τ(d, RH) ∈ (0, 16384] as a function of target distance d ∈ [0.20, 5.00] m and relative humidity.
• Host-Side Stefan-Boltzmann \(T^4\) Law (temp_correct_with_reflected_temp @ 0x2a044): Given apparent Kelvin temperature \(T_{\text{org},K} = \text{raw}_{\text{u16}} / 64.0\), surface emissivity \(\varepsilon \in (0.01, 1.0]\), transmittance \(\tau_f = \tau_{\text{u16}} / 16384.0\), reflected ambient temperature \(T_{u,K} = T_u + 273.15\), and atmospheric temperature \(T_{a,K} = T_a + 273.15\): \[ T_{\text{obj},K}^4 = \frac{T_{\text{org},K}^4 - (1 - \varepsilon)\,\tau_f\,T_{u,K}^4 - (1 - \tau_f)\,T_{a,K}^4}{\varepsilon\,\tau_f}, \qquad T_{\text{corr},^\circ\text{C}} = \left(\max\left(T_{\text{obj},K}^4, 0\right)\right)^{1/4} - 273.15 \]

6.3 HIGH_PRECISION Sub-LSB Differential Mode (< 10 mK Resolution)

To detect sub-10 millikelvin thermal transients (e.g., 1 mA PCB leakage or subtle physiological/material heating) that are normally invisible inside the P3's 62.50 mK LUT steps, HighPrecisionTracker (in P3Protocol.kt) reconfigures four hardware registers and runs a floating-point lock-in pipeline:

7. Static-Scene Temporal-Difference Compression (P3DF / /stream.diff.z) & API Reference

7.1 Why Naive Delta Fails & The 4-Stage P3DF Algorithm

Uncompressed dual-plane streaming requires 39.54 Mb/s at 25 FPS, which saturates distant Wi-Fi access points (Studio45 AP B is 27–61 Mb/s) and exceeds the 27–36 Mb/s shared internet upload ceiling. P3DiffCompressor (in P3Protocol.kt) (GET /stream.diff.z) achieves 19.7× lossless compression (2.00 Mb/s) and up to 325.1× noise-gated compression (0.12 Mb/s) in 4 stages:

1. Zero-Padding Bit Strip (v14 = raw_u16 ushr 2): Both nuct_bypass=0 and nuct_bypass=1 left-shift their 14-bit sensor words by 2 bits (bits 0..1 are always 0). Right-shifting by 2 bits before prediction losslessly removes 2 bits of padding. (In submk=1 mode, encodes round(diffMilliK * 2.0) in 0.5 mK = 500 µK steps.)
2. Closed-Loop DPCM Predictor (d = v14[t] - recon[t-1]): Computes temporal deltas against the decoder's exact reconstructed state recon. When deadband = 0, reconstruction is 100% bit-exact lossless. When deadband = k (1..3 LSBs), noise fluctuations with |d| ≤ k emit 0, while any true thermal drift exceeding k updates recon += d, guaranteeing strictly bounded error (≤ k LSBs) and zero long-term drift accumulation.
3. ZigZag Sign Folding (zz = (d shl 1) xor (d shr 31)): In two's complement int16, -1 is 0xFFFF while +1 is 0x0001. ZigZag maps 0 -> 0, -1 -> 1, +1 -> 2, -2 -> 3, +2 -> 4, making the high byte 0x00 for all |Δ| ≤ 127.
4. Plane Byte-Shuffling + InfoLine XOR-Delta + zlib: Packs all 49,152 low bytes contiguously (offset 1088..50239) followed by all 49,152 high bytes (offset 50240..99391, which is 100% zeros on static scenes!), XOR-deltas the 1,024-byte InfoLine (offset 64..1087, 99.4% zeros), and compresses the 99,392-byte buffer with Deflater.

7.2 Exact P3DF 64-Byte Header & Payload Layout (99,392 B Decompressed)

Each frame on /stream.diff.z is preceded by a 4-byte Little-Endian compressed length uint32 LE comp_len, followed by comp_len bytes of zlib data that decompress to 99,392 bytes:

struct P3DF_Packet { // Unpacks in Python via: struct.unpack("<4sBBBBqqqqqihhfBBH", raw[:64])
    char     magic[4];        // [0..3]   "P3DF" (or "P3FZ" on /stream.raw.z, "P3FR" on /stream.raw)
    uint8_t  version;         // [4]      1
    uint8_t  frameType;       // [5]      0 = KEYFRAME (I-frame), 1 = DELTA_PREV (P-frame)
    uint8_t  wireMode;        // [6]      0 = STREAMING_14B (1/16 K), 1 = HIGH_PREC_NUC14 (-38.62 mK), 2 = SUBMK_0.5MK
    uint8_t  deadband;        // [7]      DPCM deadband threshold in LSBs (0 = bit-exact lossless)
    int64_t  sequence;        // [8..15]  Monotonic frame sequence number
    int64_t  monotonicNs;     // [16..23] Host System.nanoTime()
    int64_t  wallNs;          // [24..31] Host wall-clock nanoseconds
    int64_t  cnt1;            // [32..39] P3 hardware startCnt1 (15.0 MHz / 240 MHz prescaled)
    int64_t  cnt2;            // [40..47] P3 hardware startCnt2
    int32_t  cnt3;            // [48..51] P3 hardware endCnt3 (1.000 kHz ms clock mod 2048, +40/frame)
    int16_t  width;           // [52..53] 256
    int16_t  height;          // [54..55] 192
    float    hdrFloat;        // [56..59] fpaTempC (modes 0,1) or commonModeDriftMk (mode 2)
    uint8_t  flags;           // [60]     bit0=gainHigh, bit1=autoFfc, bit2=nuctBypass, bit3=tareReady
    uint8_t  emaAlphaPct;     // [61]     round(emaAlpha * 100)
    uint16_t tareFrames;      // [62..63] Current tare frame count
    uint8_t  infoDelta[1024]; // [64..1087]      Raw InfoLine on I-frame; XOR-delta vs prevInfo on P-frame
    uint8_t  loBytes[49152];  // [1088..50239]   Low bytes of 49,152 uint16 values (ZigZag on P-frame)
    uint8_t  hiBytes[49152];  // [50240..99391]  High bytes of 49,152 uint16 values (100% 0x00 on P-frames!)
};

7.3 Live Studio45 Wi-Fi Benchmarks (25.0 FPS from Pixel 9 Pro XL)

7.4 Complete HTTP Server API Reference (Port 8080, ThermalHttpServer.kt)

7.5 Copy-Pasteable Python Client for /stream.diff.z (P3DF Decoder)

import urllib.request, zlib, struct, numpy as np

def stream_p3_diff(host="127.0.0.1", port=8080, gop=50, deadband=0, submk=0):
    """
    Streams 25 FPS temporal-difference compressed P3 frames (/stream.diff.z).
    - deadband=0: 100% bit-exact lossless (~2.00 Mb/s in STREAMING mode, ~3.57 Mb/s in HIGH_PRECISION mode)
    - deadband=1..3: closed-loop DPCM noise-gated (0.12 - 0.84 Mb/s, up to 325x compression, zero drift)
    - submk=1: streams Float64-accumulated ΔT quantized to 0.5 mK (500 µK) per LSB
    """
    url = f"http://{host}:{port}/stream.diff.z?gop={gop}&deadband={deadband}&submk={submk}"
    req = urllib.request.urlopen(url, timeout=10)
    recon = None
    info_bytes = np.zeros(1024, dtype=np.uint8)

    while True:
        hdr = req.read(4)
        if len(hdr) < 4:
            break
        (comp_len,) = struct.unpack("<I", hdr)
        comp_buf = b""
        while len(comp_buf) < comp_len:
            chunk = req.read(comp_len - len(comp_buf))
            if not chunk:
                return
            comp_buf += chunk

        raw = zlib.decompress(comp_buf)
        magic, ver, ftype, mode, db, seq, mono_ns, wall_ns, cnt1, cnt2, cnt3, w, h, hdr_f, flags, alpha_pct, tare_f = (
            struct.unpack("<4sBBBBqqqqqihhfBBH", raw[:64])
        )
        info_delta = np.frombuffer(raw, dtype=np.uint8, count=1024, offset=64)
        lo = np.frombuffer(raw, dtype=np.uint8, count=w * h, offset=1088).astype(np.uint16)
        hi = np.frombuffer(raw, dtype=np.uint8, count=w * h, offset=1088 + w * h).astype(np.uint16)
        u16 = (lo | (hi << 8)).reshape(h, w)

        if ftype == 0 or recon is None:  # Keyframe (I-frame)
            info_bytes[:] = info_delta
            if mode == 2:
                recon = ((u16 >> 1) ^ -(u16 & 1)).astype(np.int16)
            else:
                recon = u16.astype(np.int16)
        else:  # Delta frame (P-frame)
            info_bytes ^= info_delta
            delta = ((u16 >> 1) ^ -(u16 & 1)).astype(np.int16)
            recon = recon + delta

        if mode == 2:
            # Sub-mK differential mode: 0.5 mK per LSB
            diff_mk = recon.astype(np.float32) * 0.5
            yield seq, mode, comp_len, info_bytes.view("<u2"), recon, diff_mk
        elif mode == 1:
            # High-Precision raw 14-bit NUC mode (-38.62 mK / LSB)
            raw_u16 = (recon.astype(np.uint16) << 2)
            yield seq, mode, comp_len, info_bytes.view("<u2"), raw_u16, recon.astype(np.float64) * -38.62
        else:
            # Standard calibrated 1/64 K mode
            raw_u16 = (recon.astype(np.uint16) << 2)
            temp_c = (raw_u16.astype(np.float64) / 64.0) - 273.15
            yield seq, mode, comp_len, info_bytes.view("<u2"), raw_u16, temp_c

8. Remote Lab Operation, Tailscale OTA & USB Reliability on Realme 14T 5G

The lab camera host is a Realme 14T 5G (RMX5074, Tailscale host realme-14t-5g) acting as USB host for the Thermal Master P3 through a USB-C hub with charging pass-through on its single port. Measured on 15 Oct 2026 with the new hub: 1.39 A into the battery (≈5.3 W at 3.86 V), +28%/h with the P3 streaming and the screen off.

USB Disconnect & Microbump Recovery (v1.3.4+): Unplugging and replugging either the camera's USB port or the entire USB-C hub — or bumping the cable — recovers automatically without waking the phone screen (`android:turnScreenOn` is omitted so `keep_screen_on=false` stays dark):

• Microbumps (1.5 s / 3.0 s bulk timeouts): At 2 and 4 consecutive 750 ms bulk read timeouts, the reader thread performs an in-place recovery poke (0x40/0xEE clear + CMD_START_STREAM + parser sync reset) without tearing down the USB session.
• Physical Unplug & Replug: ACTION_USB_DEVICE_DETACHED immediately closes the active UsbDeviceConnection (waking any blocked bulkTransfer or interruptible handshake sleep within <100 ms), clears stale cnt3 drop tracking on the next session, and re-applies the active preset (nuct_bypass, gain, TNR/SNR, auto_ffc) after the 6-step handshake (~6.6 s).
• ColorOS USB Hub Re-Enumeration Guard: On Realme 14T (ColorOS / Android 15), calling UsbDeviceConnection.resetDevice() (USBDEVFS_RESET) through a hub causes the kernel to disconnect and re-enumerate the P3 at a new bus address (/dev/bus/usb/001/N+1) and throws SecurityException if device.serialNumber is read on the stale handle. v1.3.4 avoids resetDevice() during normal hardReset or timeout recovery (simply releasing interfaces and running a fresh 6-step handshake recovers cleanly on the same node) and reserves kernel resets for dead EP0 pipes with a 15-second cooldown.

Token-Authenticated Control, AES-256-GCM Telemetry & OTA When Tailscale Is Down (v1.3.9+): If Tailscale is down or its key expires while Wi-Fi or cellular LTE is up, the phone remains 100% controllable and upgradeable using your secret Spacesheep API key (~/.config/spacesheep/config.json) or its SHA-256 digest (token_sha256):

• Outbound Control Stream (thermal/p3-control): The phone's SS-ControlLoop polls GET https://spacesheep.dev/api/streams/thermal/p3-control?after=<cursor> every 2.5 s over outbound HTTPS, verifies token_sha256 in constant time against its configured key, executes any /api/control action or upgrade_url HTTPS APK pull (with mandatory 64-hex SHA-256 verification and HTTPS host allowlist), and publishes AES-256-GCM encrypted execution acknowledgements and network diagnostics (priv_enc) into thermal/p3-telemetry.
• Token-Protected Port 8080 HTTP: All /api/control actions, POST /api/upgrade, /api/spacesheep, and /api/probe require Authorization: Bearer <SPACESHEEP_API_KEY>, X-Auth-Token: <token>, or ?token=<sha256> by default in v1.3.9+, with cellular HTTP socket blocking and per-IP brute-force rate limiting.

# 1A. Remote unattended OTA when Tailscale IS up (no ADB, zero screen taps, Bearer token + SHA-256 verified)
cd ~/git/thermal-android
./deploy-phone.sh --http realme

# 1B. Remote unattended OTA when Tailscale is DOWN (stages APK to private GH release ota-latest,
#     dispatches token_sha256-authenticated upgrade_url over thermal/p3-control, verifies SHA-256)
./deploy-phone.sh --spacesheep

# 2. Control & inspect the phone when Tailscale is DOWN (via thermal/p3-control & thermal/p3-telemetry)
./deploy-phone.sh --status
./deploy-phone.sh --cmd "action=preset&name=raw"
./deploy-phone.sh --cmd "action=preset&name=visualize"
./deploy-phone.sh --cmd "action=close_bg_apps"

# 3. Direct HTTP over Tailscale or LAN (port 8080)
curl -s http://realme-14t-5g:8080/health | python3 -m json.tool
curl -s -H "Authorization: Bearer $SPACESHEEP_API_KEY" http://realme-14t-5g:8080/api/status | python3 -m json.tool
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://realme-14t-5g:8080/api/control?action=preset&name=raw"
curl -X POST -H "Authorization: Bearer $SPACESHEEP_API_KEY" "http://realme-14t-5g:8080/api/control?action=preset&name=visualize"