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

ZapBox - v920053 - Improvements

Since v929880 (previous release)

• Themes & Display: Added zapbox theme with inverted product QR; tuned ZAPBOX color to warm yellow; introduced btcorange-black (BTC ORANGE & BLACK) with inverted product QR; stabilized screen transitions using double-clear and adjusted safeFillScreen() to prevent stripes/artifacts.
• BTC Ticker & Navigation: Fixed ALWAYS mode in Single and Duo, corrected ticker↔QR toggling, and ensured timeouts behave consistently without redraw flooding.
• Installer: Made ZAPBOX the default theme, renamed black-yellow to black-btcorange, added the new BTC ORANGE & BLACK option, and updated firmware dropdown for the new release.
• Config Mode UX: Added exit via NEXT/HELP buttons and general UI improvements.
• API & Networking: Simplified BTC fetch (sequential), added backoff and SSL cleanup to avoid ticker errors, increased task stack size for HTTPS stability, and improved startup connectivity checks.
• Logging & Refactor: Replaced Serial prints with LOG_* macros across modules, added log helper and set LOG_LEVEL to Info; consolidated LNURL/QR updates and initial-screen selection; split modules (UI, Network, Input, Payment, Navigation, Utils) for clearer architecture.
• State Machine Migration: Completed move to DeviceState-driven architecture and global state struct accessors.
• External Button: Made external LED button optional via build flag, with minor notification tweaks.

ZapBox - v929880 - Code Refactoring 🔧

🏗️ Architectural Restructuring

• main.cpp reduced by 42% (3,149 → 1,823 lines, -1,326 lines!)
• State Machine Architecture: DeviceState enum replaces scattered sync variables
• GlobalState Struct: All global variables migrated to structured data types
• Module Extraction:
  • Payment.cpp - LNURL generation & QR management
  • Input.cpp - Physical & touch button event handling
  • Network.cpp - WiFi, Internet, WebSocket connectivity
  • UI.cpp - Display orchestration, LED control, power-saving
  • Navigation.cpp - Multi-product navigation & touch logic
  • API.cpp - Bitcoin data & switch label fetching
  • Utils.cpp - Shared helper functions

🪵 Structured Logging System

• Custom Log.h with 4 levels (ERROR/WARN/INFO/DEBUG)
• Compile-time filtering, millisecond timestamps
• ~100+ Serial.println calls replaced across all modules

🔌 Pin Management Optimization

• Array-based label system eliminates repetitive if-else chains
• getPinIndex() helper for clean pin-to-index mapping

🐛 Critical Bug Fixes

• SSL Memory Exhaustion: 30-second backoff prevents rapid retry loops
• Internet detection: 2s stabilization + 3x retry logic
• Sequential BTC API requests prevent SSL conflicts

📦 Code Quality

• Modular, maintainable architecture
• Clear separation of concerns
• Production-safe logging configuration