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

ZapBox - v929761 - External LED button

Bug fixes and external LED button

Major Features:

1. External LED Button (v929761)

   • GPIO 43 (LED) + GPIO 44 (Button) Support
   • Single Click → Navigate, 2s Hold → Help, Triple → Report, Double+Hold 3s → Config
   • Debounce Logic with Edge-Detection

2. Orientation Support (9f35572)

   • 4 Orientations: h (horizontal), v (vertical), hi (horizontal inverse), vi (vertical inverse)
   • Complete repositioning of QR codes, labels, buttons for each orientation

3. NFC Reader PN532 (3a86c96)

   • I2C integration with PN532
   • Removed external RST pin (HW-147 has none)

4. Product Navigation & Label Loading (e5d7cee)

   • Quattro Mode: After last product → BTC Ticker → Back to product 1
   • Label reload every 5 minutes with retry
   • Improved navigation between screens

5. UI/UX Improvements

   • Web Installer Redesign (16fbab5)
   • Button Label Mirroring for Inverse Orientations
   • QR Code Repositioning for all Orientations
   • HELP Text Orientation Fix

6. Display Tweaks

   • Inverse Orientation Positioning Fine-Tuning
   • Font Size Adjustments
   • QR Code Size Optimizations

7. GPIO Handling

   • GPIO13 Separation from Threshold Mode (8cb5286)
   • Wake-up Grace Period Optimization (b1f57c6)

8. Bug Fixes

   • Screensaver Wake-on-Touch (31dfcbd)
   • WiFi Recovery Crashes (31dfcbd)
   • Hybrid Touch Gesture Handling (ccf5158)

ZapBox - v929311 - BTC-Ticker Touch Control

BTC-Ticker Touch Control & Debounce

Highlights

✨ Touch support for BTC-Ticker modes - toggle between ticker and QR with a tap
🛠️ Fixed touch polling/flickering when swiping across display
⚙️ Improved "always" mode behavior with proper timeout handling
🎨 Reorganized web installer for better usability

Key Features

• Touch Control: Tap ticker to show QR temporarily, automatic return after timeout
• Smart Debounce: 300ms debounce prevents multiple actions per touch gesture (all modes)
• Separate Timeouts: PRODUCT_TIMEOUT (20s) and BTCTICKER_TIMEOUT (10s) for different navigation directions
• Always Mode: Ticker stays primary, touch shows QR on demand (Single/Duo/Quattro)
• Selecting Mode: Touch displays ticker for 10 seconds when needed

Bug Fixes

• Fixed Single mode "always" starting with QR instead of ticker
• Eliminated screen flickering during swipe gestures (Duo/Quattro)
• Removed unintended automatic switching in always mode
• Applied debounce logic to all modes, not just Single

Web Installer Updates

• Reorganized sections with clearer structure
• Added touch wake-up capability notes
• Simplified section headers for better overview

ZapBox - v929126 - Touch & Multi-Channel

Major Features

Touch Control & Multi-Channel-Control Mode 🎉

Touch Functionality Integration

• First implementation of complete touch display support for T-Display-S3 Touch variant
• Hardware: CST816S touch controller with 170×320 resolution
• Gesture detection: SWIPE (all directions), SINGLE_CLICK, GESTURE_NONE
• Coordinate handling: Hardware-based (0-170 × 0-320), orientation-independent

Virtual Touch Button (specific touch feature)

• Bottom area (Y>305, 15px height) reserved as virtual button
• Click patterns: 1× Help, 2× Report, 4× Config
• 100ms debounce, 1s timeout between clicks
• Works in all display orientations

Multi-Channel-Control Mode

• Support for up to 4 products (Pins 12/13/10/11)
• Individual LNURLs per product
• Touch navigation: swipe between products, tap to switch
• Fetches device labels via API (/api/v1/public/{deviceId})

Improvements

• Currency symbol support (€, $, ¥)
• Code consolidation
• Extended Help Mode to 3×1s screens
• Config Mode timeout: 60s

Compatibility

• Backward Compatible: Works with older bitcoinswitch extensions
• Recommended: Update extension to latest version for label support
• Breaking Changes: None

Commits

afffc94 touch control
09bf9ec docs: Update release description
299af73 docs: Rename Multi-Control to Multi-Channel-Control
c852396 Release v929126
04306ba docs: Update README with Touch features
3ac3e09 feat: Touch button implementation
e52f37d docs: Multi-Control Mode documentation
4bd2d11 feat: Code consolidation and currency symbol support
c025e18 feat: Multi-Control Mode mit Touch-Navigation
4d00f57 feat: Add Multi-Control/Product Selection
47a65d7 feat: Implement touch functionality
b04d579 Update docu start up screen time

Hardware Support

• LilyGo T-Display-S3 (Non-Touch): Standard operation
• LilyGo T-Display-S3 Touch: Full touch control enabled

ZapBox - v928945 - Smart Start

Proactive error detection and optimized startup sequence for faster boot times and immediate error feedback.

Features

• Proactive error detection: Error screens displayed BEFORE connection confirmation
• Connection confirmation tracking: Four-level verification system (WiFi → Internet → Server → WebSocket)
• Parallel startup optimization: WiFi connection starts immediately during startup screen
• Optimized startup sequence: 5 seconds startup screen + up to 20 seconds initialization
• Early exit capability: Startup completes as soon as all connections confirmed (typically 10-15 seconds)
• Smart auto-recovery: QR code automatically redraws after WiFi/WebSocket reconnection
• Priority-based error handling: WiFi issues prevent false "No Internet" errors
• Active WebSocket reconnection: 5-second active wait ensures reliable connection after WiFi recovery

Technical Improvements

• Added initialization screen with "Initialization in progress . . ." indicator
• WiFi.begin() moved before startup screen for parallel connection establishment
• Connection confirmation flags: wifiConfirmed, internetConfirmed, serverConfirmed, websocketConfirmed
• QR code redraw integrated in checkAndReconnectWiFi() after WebSocket connection
• QR code redraw in 5-second auto-recovery loop when all connections confirmed
• Internet connectivity check skips if WiFi is down (prevents cascading false positives)
• Active webSocket.loop() calls during 5-second post-reconnection wait
• Enhanced README documentation with detailed startup sequence explanation

User Experience Improvements

• Faster feedback: Errors displayed immediately, no waiting for completion
• No stuck screens: Auto-recovery ensures display updates after reconnection
• Reliable recovery: WebSocket reconnection properly waits for connection establishment
• Clear priority: WiFi status checked first, preventing misleading error messages

Documentation Updates

• Added "Startup & Initialization Sequence" section to README
• Documented two-phase startup process
• Explained parallel connection establishment
• Clarified early exit behavior

Breaking Changes

None - fully backward compatible with previous configurations.