116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
# ESP32-S3 TQ Thermal Printer Firmware (No Business HTTP Server)
|
|
|
|
This firmware now runs in printer mode and does not expose the previous
|
|
business REST endpoints (`/v1/*`).
|
|
|
|
## Features
|
|
|
|
- Thermal printer driver (single printer path)
|
|
- Auto-initialize printer driver 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 Printer 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`
|
|
- Thermal printer runtime and safety policy:
|
|
- `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_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
|
|
```
|