# 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

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

## Flash

```bash
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`](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:

```bash
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
```