ESP32-S3 TQ Printer Controller (Direct Thermal, No Business HTTP Server)

This firmware now runs in direct-printer mode and does not expose the previous business REST endpoints (/v1/*).

Features

• Direct thermal printer backend (PRINTER_BACKEND_DIRECT)
• Auto-connect direct printer during startup
• Async print queue and worker lifecycle management
• Printer precheck (paper / battery / temperature)
• MIC key push-to-talk voice flow (button-triggered, no HTTP trigger)
• Wi-Fi STA with SoftAP provisioning fallback
• Provisioning portal page at http://192.168.4.1 (unchanged)
• Optional DashScope Z-Image integration for image generation

What Was Removed

• Business HTTP server in control_plane (including previous /, /v1/health, /v1/printer/*, /v1/print/*, /v1/jobs*, /v1/voice/* endpoints)
• Related Kconfig items:
  • TQ_HTTP_PORT
  • TQ_API_KEY

Build

Prerequisites:

• ESP-IDF v5.x
• ESP32-S3 board

cd ai_printer
idf.py set-target esp32s3
idf.py menuconfig
idf.py build

Flash

cd ai_printer
idf.py -p /dev/tty.usbmodemXXXX flash monitor

Config

In menuconfig -> TQ Controller Config:

• Wi-Fi provisioning:
  • TQ_WIFI_PROV_SOFTAP_SSID
  • TQ_WIFI_PROV_SOFTAP_PASSWORD
  • TQ_WIFI_PROV_SOFTAP_CHANNEL
  • TQ_WIFI_PROV_SOFTAP_MAX_CONN
• Direct thermal printer runtime and safety policy:
  • TQ_DIRECT_PRINTER_*
  • TQ_PRINTER_*
• Z-Image HTTP fields:
  • TQ_Z_IMAGE_API_KEY (optional, empty means fallback to TQ_VOICE_API_KEY)
  • TQ_Z_IMAGE_API_ENDPOINT
  • TQ_Z_IMAGE_MODEL
  • TQ_Z_IMAGE_DEFAULT_SIZE
  • TQ_Z_IMAGE_TIMEOUT_MS
  • TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS
• Voice and audio fields (used by MIC key push-to-talk flow):
  • TQ_VOICE_*
• Board GPIO map:
  • TQ_POWER_*, TQ_LED_*, TQ_SCREEN_*, TQ_PRINT_*, TQ_SPI_*
  • TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT / TQ_KEY_PRINT_BOOST_ACTIVE_HIGH
• ST7789 screen fields:
  • TQ_SCREEN_ENABLE
  • TQ_SCREEN_TEST_PATTERN_ON_BOOT
  • TQ_SCREEN_PIXEL_CLOCK_HZ
  • TQ_SCREEN_SPI_MODE
  • TQ_SCREEN_H_RES / TQ_SCREEN_V_RES
  • TQ_SCREEN_DRAW_LINES
  • TQ_SCREEN_COLOR_ORDER_BGR
  • TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH
  • TQ_SCREEN_MIRROR_* / TQ_SCREEN_SWAP_XY
  • TQ_SCREEN_X_GAP / TQ_SCREEN_Y_GAP
  • TQ_SCREEN_RESET_PIN

Board pin assignment reference:

• docs/gpio-map.md

Wi-Fi Provisioning Behavior

• Device first tries saved STA credentials from NVS (wifi_cfg namespace)
• If credentials are invalid or STA connect fails, device starts SoftAP portal
• Open http://192.168.4.1 and submit credentials from the provisioning page
• Provisioning page supports Chinese/English switching and local language cache
• Credentials are written to NVS only after STA connect succeeds

Notes

• This project no longer provides business HTTP API endpoints for print/voice/job control.
• SoftAP provisioning HTTP service remains enabled by design.
• UTF-8 Chinese text rendering uses embedded 16x16 GB2312 glyphs.
• Large image buffers prefer PSRAM, then fall back to internal RAM.
• Partition table uses partitions.csv with a 4MB factory app partition on 16MB flash modules.

Font Assets

Embedded files:

• components/domain/assets/fonts/cn16_index.bin
• components/domain/assets/fonts/cn16_glyphs.bin

Regenerate from your own CJK font:

cd ai_printer
python3 -m pip install --user pillow
python3 tools/gen_cn16_font.py \
  --font app/src/main/assets/fonts/msyh.ttc \
  --font-index 0