ZapBox - v939296 - Huge and Valuable Update 🛡

🛡️ Display Thread-Safety (Both Versions)

• Recursive FreeRTOS SPI mutex protects all 28 display functions from concurrent access between Core 0 (button callbacks: Help, Config, Report, Navigation) and Core 1 (main loop) — eliminates display corruption (horizontal stripes, garbled pixels, wrong colors)
• RAII DisplayLock guard pattern ensures automatic mutex release even on early returns

⚡ NFC Reliability (Both Versions)

• Double-trigger prevention: Card removal detection with 2 consecutive absent polls (~0.8s) prevents duplicate payments
• NO LUCK timeout screen after 60s pending state — no more stuck "PENDING NFC" screens
• Smarter error handling: HTTP errors keep pending state instead of premature NO LUCK (server may still confirm via WebSocket)
• Fixed ENABLE_NFC=0 preprocessor bug (#ifdef vs #if) that silently disabled NFC monitoring
• Removed unsafe cross-core display call from NFC network handler

🌐 WebSocket Recovery (Both Versions)

• Fixed zombie connections after boot without WiFi — proper disconnect() + fresh beginSSL() + active webSocket.loop() polling
• QR screen auto-redraw after successful WebSocket reconnect recovery

📐 Housing Updates

• Added e-layout Compact with NFC
• Added b939002 Compact 35° with NFC cap

ZapBox - v938908 – NTAG21x/LNURL NFC Tag Support

Here's the GitHub release description for v938908 / v938908h:

---

⚡ ZapBox Firmware v938908 & v938908h

✨ New Feature – Plain NFC Tag Support (NTAG213/215/216)

ZapBox now supports plain NDEF NFC tags containing an LNURL-withdraw link in addition to NTAG424 Bolt Cards.

How it works:

• Write an lnurl1... or lightning:lnurl1... URL onto any NTAG213/215/216 tag using any NFC writing app
• Tap the tag on the ZapBox reader → payment is triggered instantly
• NTAG424 Bolt Cards continue to work exactly as before — no breaking change

---

🛠️ Extension Updates (zapbox_extension v2.0.2 → v2.0.3)

v2.0.3 – Fixed a payment tag conflict with bitcoinswitch_extension
Both extensions previously listened for payments tagged "Switch". The ZapBox extension now uses the tag "ZapBox", fully isolating the two extensions from each other.

v2.0.2 – Fixed a race condition with fast Bolt Card payments
Very fast payments (e.g. Bolt Card NFC tap) could settle before the switch payment record was committed to the database, resulting in a WARNING | Switch payment not found log entry. Added a retry loop to handle this gracefully.

⚠️ If you use both zapbox_extension and bitcoinswitch_extension, update to v2.0.3 of zapbox_extension.

---

📦 Versions

Version	Target Hardware	Notes
v938908	LILYGO T-Display-S3	Standard version with display
v938908h	ESP32 Dev Board	Headless version, 12 relay channels

---

🔗 Web Installer

Flash directly from your browser: installer.zapbox.space

ZapBox - v938689 - NFC fix & headless update

🎯 Release v938689 & v938689h – NFC Fix, Headless 12 Relays & Config Read Fix

🐛 Bug Fixes

• NFC card tap ignored when device is not ready – If a card was placed on the reader while the ZapBox was in an error state (NO WIFI / NO INTERNET / NO WEBSOCKET) or still booting, the NFC pending state was incorrectly triggered and the LED started blinking in the NFC rhythm. Card taps are now silently discarded in states INITIALIZING, CONNECTING_WIFI, ERROR_CRITICAL and ERROR_RECOVERABLE.

• Config "Read" now reliably fills form fields – The web installer sometimes did not populate the form fields when clicking "Read Config". Root cause: the ESP32-S3 USB CDC can drop bytes at chunk boundaries, corrupting the /file-read prefix (e.g. arriving as /file-rea). The parser now detects the config JSON directly in the buffer – independent of the prefix.

✨ Features

• Firmware version shown in serial log – After boot, the active firmware version is printed below ZapBox ready! 🎉: Firmware: v938689

• Headless: 12 relay channels – The headless version (ESP32-WROOM-32) now supports up to 12 relay channels instead of 8, fully compatible with the ESP32-WROOM-32 GPIO layout.

ZapBox - v938321 - NFC Bolt Card Support 🃏⚡

⚡ NFC Bolt Card Support

This release adds full NFC Bolt Card payment support to ZapBox – tap your Bolt Card on the PN532 module and the relay fires automatically via the zapbox_extension.

🆕 New Features

• NFC Bolt Card payments via PN532 module (I2C) – available on both display and headless firmware
• NFC payment pending screen – shows a dedicated screen while the payment is being processed
• LED feedback during NFC flow: slow blink while waiting → 2× quick confirm blinks when relay fires → LED stays ON
• ENABLE_NFC_TEST mode – hardware test without a server (blinks LED on card read)
• zapbox_extension auto-detect – firmware automatically picks up the correct API path (/bitcoinswitch → /zapbox fallback)
• zapbox_extension v2.0.1 integrated (fixes listener collision with bitcoinswitch_extension)
• actionTimeScreen redesigned to match nfcPendingScreen style (inverted "TIME" box)

🐛 Bug Fixes

• Fixed 23-second hang on boot when no PN532 hardware is connected (I2C probe before getFirmwareVersion())
• Fixed race condition: invoice settles before create_switch_payment commits to DB – bitcoinswitch_id now stored in payment.extra as fallback
• Fixed listener name collision between zapbox_extension and bitcoinswitch_extension ("ext_zapbox" vs "ext_bitcoinswitch")
• NFC payment timeout increased from 30s → 45s (reset only after successful POST, not before)
• Fixed brief LED-off gap after "All connections confirmed" on boot (initializationActive cleared immediately)
• Fixed ready LED not restored after NFC payment failure

📡 Headless (ESP32 Dev)

• ENABLE_NFC=1 in esp32dev environment
• Wire.begin() only called on headless to avoid I2C conflicts with display hardware
• GPIO 4 used for NFC IRQ

🔧 Installer

• Helpful links section moved into the blue troubleshoot div
• MakerBits Telegram link added
• Wiring images for PN532 added to both installers

---

Standard firmware (LilyGo T-Display-S3): v938617
Headless firmware (ESP32 Dev): v938617h

Use the ZapBox Web Installer to flash directly from your browser.

ZapBox - v938321 - Ambient Lighting Switch

✨ New Feature: Channel 4 Ambient Lighting Switch

• Add special function for channel 4: Ambient lighting mode
• GPIO 11 syncs automatically with display backlight
• Perfect for vending machine lighting that follows screen state
• Display ON → Channel 4 ON (lighting active)
• Screensaver mode → Channel 4 OFF (power saving)
• Only 3 products available in quattro mode when enabled

🔧 Improvements

• Reduced BTC ticker timeout from 15s to 10s
• Increased report screen display time from 2s to 5s
• Reorganized web installer Multi-Channel Mode section
• Changed "Multi-Channel-Control" to "Multi-Channel-Mode"

ZapBox - v936258 - Vending machine

Release v936258 - Changelog

General Improvements (all versions)

🔒 NULL-Pointer Protection

• All config values secured with null-checks
• Prevents crashes on missing or corrupted configuration data

📡 Web Installer Improvements

• Gentle user guidance instead of hard disconnects
• Popup instructions for Config-Mode entry
• Enhanced log output in terminal
• Improved boot sequence detection
• Automatic device reset detection
• No automatic connection timeout (prevents reset loops)

🔧 CP2102 Serial-Fix

• flowControl set to 'none' to prevent unwanted DTR/RTS manipulation
• Documentation for CP2102 reset-loop workaround added

📁 Assets Update

• Added headless housing designs (b935750-Headless)
• Added headless electrical schematics (assets/electric/e935776 Headless/)

---

Standard Version (T-Display-S3) - v936258

✨ Vending Machine Light Barrier (GPIO 2)

• Optional activation via Web Installer
• NPN light sensor (active LOW with INPUT_PULLUP)
• Stops action after minimum 2 seconds elapsed
• Integration in all 3 relay modes (Normal, Threshold, Special)
• Config Index: 19
• GPIO 2 exclusive to T-Display-S3 (#ifdef PIN_LIGHT_BARRIER)
• Config indices shifted: currency→20, externalButton→21

---

Headless Version (ESP32 Dev) - v936258h

🔧 Serial-Fix

• Repair serial communication - Enable reconnection

Boot Indicator

• LEDs (GPIO 21 + onboard GPIO 2) blink 3× rapidly on startup (100ms on/off)
• Visual confirmation that device is booting correctly

ZapBox - v933714(h) - Updates & Bugfixes

New Features

• GPIO 2 Onboard LED Support (Headless): ESP32 Dev onboard LED (GPIO 2) now mirrors GPIO 21 status output for easier debugging
• Config Mode Indication: Both LEDs blink at 1Hz when device is in configuration mode (headless version only)
• Ready Status Message: Added "ZapBox ready! 🎉" message when device is ready to receive payments

Technical Changes

• Added PIN_ONBOARD_LED definition for GPIO 2 in esp32dev configuration
• Extended updateReadyLed() to control both GPIO 2 and GPIO 21 simultaneously
• Implemented LED blinking logic in SerialConfig.cpp for visual config mode feedback
• Updated web installer documentation with GPIO pin information

Firmware Variants

• v933714: Standard version for LilyGo T-Display-S3 (with display)
• v933714h: Headless version for ESP32 Dev Module (GPIO status LEDs only)

Files Changed

• PinConfig.h: Added GPIO 2 pin definition
• main.cpp: Added ready message and GPIO 2 initialization
• UI.cpp: Extended LED control to GPIO 2
• SerialConfig.cpp: Added LED blinking in config mode
• index.html: Updated documentation

ZapBox - v933545(h) - Headless 🍬

Release v933545 & v933545h

🎯 Major New Feature

• 🆕 Headless Version (v933545h) - First official release of ESP32 Dev Module headless version for use without display! Perfect for integration scenarios, status monitoring via serial console, and LED-based status indication (GPIO 21)

🔧 Bug Fixes & Stability

• WebSocket Stability - Improved WebSocket connection stability with implemented payment queue system for more reliable payment processing
• Display Rotation Fix - Fixed display rotation bug for inverted color themes (T-Display-S3)
• LED-Button Config Exit - Fixed GPIO 42 LED-Button config mode exit functionality

⚡ Features & Improvements

• Payment Queue System - New queue-based payment processing prevents payment loss during connection issues
• Headless LED Control - Optimized LED control for headless version with conditional compilation
• Web Installer - Web installer interface improvements with separate headless firmware option
• LED-Button Option - New configuration option for active LED-Button control

🏗️ Hardware Support

• New hardware variants: Illuminated Sign (b932788), Compact (b932506), Quattro (b932595)
• Updated E-layouts for Duo and Quattro
• FreeCAD models and fonts updated

📦 Available Versions

• v933545 - Standard T-Display-S3 version (16MB Flash) - with full display support
• v933545h - 🆕 Headless ESP32 Dev Module version (4MB Flash) - no display required

---

Installation: https://installer.zapbox.space/

ZapBox - v930750 - White Paper Release

This release officially documents the ZapBox project with a comprehensive White Paper, timestamped on the Bitcoin blockchain.

White Paper

• Version: wp930750
• Languages: German & English (full translation)
• Blockchain Timestamps for:
  • Block 930758 (opreturnbot.com) - TX: 9c67ae0c7edc61b4d1913291ea17fdfa29a50e7c4a6baf89ced2f8f04c8dc7d9
  • Block 930759 (poststr.com) - TX: d51fab2eff9f85af7a332e29eef8c0d7f41f42ec36e78a40a36c1fe77a73d9b6
• SHA-256 Hash: 99e1fc06e9b896c6f8c34f1b1ef3046c2a868f8de52e10e05b51c11d29f7f49f for white-paper-wp930750-en.pdf

Firmware Changes (since v930331)

Display Theme Improvements:

• Updated: "white-black" → "black-darkcyan" (better contrast)
• Updated: "darkgrey-lightgrey" → "black-darkgrey" (improved readability)
• Removed: "yellow-black" (theme consolidation)

ZapBox - v930331 - Golden Timer

🎨 Visual Improvements

• Changed zapbox theme from yellow (0xD600) to gold (0xFEA0 / #FFD700)
  • More aesthetically pleasing appearance
  • More stable RGB565 bit pattern with full red channel (31/31) vs. partial (26/31)
  • Significantly improved display controller stability - eliminates screen corruption issues

🐛 Bug Fixes

Display Controller Stability (Major Fix)

• Resolved critical display corruption that plagued the zapbox theme:
  • Eliminated black/yellow vertical stripes when switching between ticker and QR screens
  • Fixed completely black screen issues (backlight on, no content)
  • Fixed half-rendered screens with mixed content
• Root cause: ST7789 display controller instability during complete color inversions (BLACK↔YELLOW)
• Solution: Gold color (0xFEA0) has similar bit pattern to orange (0xFCC0) which never had issues
• Multiple debugging iterations with double-clear sequences and timing delays coordinated

BTC Ticker Improvements

• Reduced flicker during auto-updates: implemented partial update function that only refreshes price/sats/block values instead of full screen redraw
• Improved Bitcoin data retry logic: 1-minute retry on errors (Price/Block Height failures) instead of 5-minute wait for faster recovery on startup

Navigation Race Condition

• Fixed: NEXT button now works on first press from product selection screen
• Previously required two presses in Duo/Quattro "when selecting" mode
• Solution: Timer reset moved earlier to prevent race condition with timeout check