From 8df2095acf89d1fdab3d3056558d3248d8898383 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 28 Feb 2026 16:41:12 +0800 Subject: [PATCH] chore(repo): keep only current main snapshot History squashed to one root commit to permanently drop old branch history and objects. --- .gitignore | 13 + .vscode/settings.json | 11 + AGENTS.md | 60 + CMakeLists.txt | 3 + README.md | 374 +++++ components/app_composition/CMakeLists.txt | 10 + components/app_composition/README.md | 8 + components/app_composition/include/.gitkeep | 0 .../app_composition/include/app_composition.h | 13 + components/app_composition/internal/.gitkeep | 0 components/app_composition/src/.gitkeep | 0 components/app_composition/src/app_main.c | 21 + components/control_plane/CMakeLists.txt | 21 + components/control_plane/README.md | 8 + components/control_plane/include/.gitkeep | 0 .../control_plane/include/control_plane.h | 37 + components/control_plane/internal/.gitkeep | 0 .../internal/rest_server_internal.h | 63 + components/control_plane/src/.gitkeep | 0 .../control_plane/src/controller_lifecycle.c | 310 +++++ components/control_plane/src/rest_server.c | 1216 +++++++++++++++++ .../control_plane/src/rest_server_common.c | 187 +++ .../control_plane/src/rest_server_jobs.c | 173 +++ .../control_plane/src/rest_server_ops.c | 807 +++++++++++ .../control_plane/src/rest_server_print.c | 135 ++ .../src/rest_server_print_image.c | 661 +++++++++ .../src/rest_server_print_render.c | 540 ++++++++ .../control_plane/src/rest_server_voice.c | 213 +++ components/domain/CMakeLists.txt | 37 + components/domain/README.md | 9 + .../domain/assets/fonts/cn16_glyphs.bin | Bin 0 -> 238240 bytes components/domain/assets/fonts/cn16_index.bin | Bin 0 -> 44670 bytes components/domain/include/.gitkeep | 0 components/domain/include/domain.h | 381 ++++++ components/domain/internal/.gitkeep | 0 .../internal/printer_protocol_internal.h | 124 ++ .../internal/voice_interaction_internal.h | 134 ++ components/domain/src/.gitkeep | 0 .../domain/src/domain_runtime_contracts.c | 201 +++ components/domain/src/image_generation.c | 962 +++++++++++++ components/domain/src/printer_protocol.c | 1024 ++++++++++++++ .../domain/src/printer_protocol_commands.c | 433 ++++++ components/domain/src/printer_protocol_jobs.c | 358 +++++ .../domain/src/printer_protocol_worker.c | 464 +++++++ components/domain/src/raster_tools.c | 467 +++++++ components/domain/src/raster_tools_image_qr.c | 531 +++++++ components/domain/src/screen_preview.c | 22 + components/domain/src/system_runtime.c | 34 + components/domain/src/voice_interaction.c | 529 +++++++ .../domain/src/voice_interaction_common.c | 488 +++++++ .../domain/src/voice_interaction_marker.c | 520 +++++++ .../domain/src/voice_interaction_tasks.c | 154 +++ components/domain/src/voice_interaction_ws.c | 340 +++++ .../domain/src/voice_interaction_ws_audio.c | 99 ++ .../src/voice_interaction_ws_protocol.c | 252 ++++ components/domain/third_party/qrcodegen.c | 1027 ++++++++++++++ components/domain/third_party/qrcodegen.h | 385 ++++++ components/platform/CMakeLists.txt | 36 + components/platform/README.md | 13 + components/platform/assets/lcd_demo.png | Bin 0 -> 187043 bytes components/platform/include/.gitkeep | 0 components/platform/include/platform.h | 240 ++++ components/platform/internal/.gitkeep | 0 .../internal/display_lcd_decode_image.h | 20 + .../platform/internal/display_lcd_module.h | 31 + .../platform/internal/display_st7789p3.h | 97 ++ components/platform/src/.gitkeep | 0 components/platform/src/ble_printer_client.c | 706 ++++++++++ .../platform/src/direct_thermal_printer.c | 1020 ++++++++++++++ .../platform/src/display_lcd_decode_image.c | 139 ++ components/platform/src/display_lcd_module.c | 904 ++++++++++++ components/platform/src/display_st7789.c | 43 + components/platform/src/display_st7789p3.c | 575 ++++++++ components/platform/src/platform_bootstrap.c | 244 ++++ components/platform/src/runtime_diagnostics.c | 136 ++ components/platform/src/runtime_policy.c | 319 +++++ components/platform/src/voice_audio.c | 496 +++++++ components/platform/src/wifi_manager.c | 325 +++++ dependencies.lock | 76 ++ dependency_whitelist.md | 13 + docs/gpio-map.md | 65 + docs/websocket.md | 1164 ++++++++++++++++ docs/z-image.md | 268 ++++ main/CMakeLists.txt | 3 + main/Kconfig.projbuild | 580 ++++++++ main/idf_component.yml | 21 + partitions.csv | 4 + sdkconfig.defaults | 107 ++ tools/gen_cn16_font.py | 130 ++ 89 files changed, 21634 insertions(+) create mode 100644 .gitignore create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md create mode 100644 CMakeLists.txt create mode 100644 README.md create mode 100644 components/app_composition/CMakeLists.txt create mode 100644 components/app_composition/README.md create mode 100644 components/app_composition/include/.gitkeep create mode 100644 components/app_composition/include/app_composition.h create mode 100644 components/app_composition/internal/.gitkeep create mode 100644 components/app_composition/src/.gitkeep create mode 100644 components/app_composition/src/app_main.c create mode 100644 components/control_plane/CMakeLists.txt create mode 100644 components/control_plane/README.md create mode 100644 components/control_plane/include/.gitkeep create mode 100644 components/control_plane/include/control_plane.h create mode 100644 components/control_plane/internal/.gitkeep create mode 100644 components/control_plane/internal/rest_server_internal.h create mode 100644 components/control_plane/src/.gitkeep create mode 100644 components/control_plane/src/controller_lifecycle.c create mode 100644 components/control_plane/src/rest_server.c create mode 100644 components/control_plane/src/rest_server_common.c create mode 100644 components/control_plane/src/rest_server_jobs.c create mode 100644 components/control_plane/src/rest_server_ops.c create mode 100644 components/control_plane/src/rest_server_print.c create mode 100644 components/control_plane/src/rest_server_print_image.c create mode 100644 components/control_plane/src/rest_server_print_render.c create mode 100644 components/control_plane/src/rest_server_voice.c create mode 100644 components/domain/CMakeLists.txt create mode 100644 components/domain/README.md create mode 100644 components/domain/assets/fonts/cn16_glyphs.bin create mode 100644 components/domain/assets/fonts/cn16_index.bin create mode 100644 components/domain/include/.gitkeep create mode 100644 components/domain/include/domain.h create mode 100644 components/domain/internal/.gitkeep create mode 100644 components/domain/internal/printer_protocol_internal.h create mode 100644 components/domain/internal/voice_interaction_internal.h create mode 100644 components/domain/src/.gitkeep create mode 100644 components/domain/src/domain_runtime_contracts.c create mode 100644 components/domain/src/image_generation.c create mode 100644 components/domain/src/printer_protocol.c create mode 100644 components/domain/src/printer_protocol_commands.c create mode 100644 components/domain/src/printer_protocol_jobs.c create mode 100644 components/domain/src/printer_protocol_worker.c create mode 100644 components/domain/src/raster_tools.c create mode 100644 components/domain/src/raster_tools_image_qr.c create mode 100644 components/domain/src/screen_preview.c create mode 100644 components/domain/src/system_runtime.c create mode 100644 components/domain/src/voice_interaction.c create mode 100644 components/domain/src/voice_interaction_common.c create mode 100644 components/domain/src/voice_interaction_marker.c create mode 100644 components/domain/src/voice_interaction_tasks.c create mode 100644 components/domain/src/voice_interaction_ws.c create mode 100644 components/domain/src/voice_interaction_ws_audio.c create mode 100644 components/domain/src/voice_interaction_ws_protocol.c create mode 100644 components/domain/third_party/qrcodegen.c create mode 100644 components/domain/third_party/qrcodegen.h create mode 100644 components/platform/CMakeLists.txt create mode 100644 components/platform/README.md create mode 100644 components/platform/assets/lcd_demo.png create mode 100644 components/platform/include/.gitkeep create mode 100644 components/platform/include/platform.h create mode 100644 components/platform/internal/.gitkeep create mode 100644 components/platform/internal/display_lcd_decode_image.h create mode 100644 components/platform/internal/display_lcd_module.h create mode 100644 components/platform/internal/display_st7789p3.h create mode 100644 components/platform/src/.gitkeep create mode 100644 components/platform/src/ble_printer_client.c create mode 100644 components/platform/src/direct_thermal_printer.c create mode 100644 components/platform/src/display_lcd_decode_image.c create mode 100644 components/platform/src/display_lcd_module.c create mode 100644 components/platform/src/display_st7789.c create mode 100644 components/platform/src/display_st7789p3.c create mode 100644 components/platform/src/platform_bootstrap.c create mode 100644 components/platform/src/runtime_diagnostics.c create mode 100644 components/platform/src/runtime_policy.c create mode 100644 components/platform/src/voice_audio.c create mode 100644 components/platform/src/wifi_manager.c create mode 100644 dependencies.lock create mode 100644 dependency_whitelist.md create mode 100644 docs/gpio-map.md create mode 100644 docs/websocket.md create mode 100644 docs/z-image.md create mode 100644 main/CMakeLists.txt create mode 100644 main/Kconfig.projbuild create mode 100644 main/idf_component.yml create mode 100644 partitions.csv create mode 100644 sdkconfig.defaults create mode 100644 tools/gen_cn16_font.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..eef899c --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +build/ + +# ESP-IDF local config artifacts +sdkconfig* +!sdkconfig.defaults + +# Local editor/OS/cache noise +.DS_Store +__pycache__/ +.pytest_cache/ + +managed_components +JX_2R_01测试程序_STM32F103RF \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..235fa80 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,11 @@ +{ + "idf.currentSetup": "/Users/moyyang/esp/v5.5.2/esp-idf", + "idf.flashType": "UART", + "idf.port": "/dev/tty.usbserial-110", + "idf.openOcdConfigs": [ + "board/esp32s3-builtin.cfg" + ], + "idf.customExtraVars": { + "IDF_TARGET": "esp32s3" + } +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..49817d8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# Repository Guidelines + +## Project Structure & Layering +- `components/platform/{include,internal,src}`: hardware/system abstraction only. +- `components/domain/{include,internal,src}`: business-domain services. +- `components/control_plane/{include,internal,src}`: lifecycle, policy, health, retry/backoff orchestration. +- `components/app_composition/{include,internal,src}`: composition boundary; `app_main` only wires modules. +- `dependency_whitelist.md`: approved exceptions for unavoidable lateral dependencies. +- `components/domain/third_party/`, `components/domain/assets/fonts/`, `tools/`: vendored code, embedded assets, utility scripts. +- `build/`: generated artifacts only (ignored). + +## Mandatory Architecture Constraints +1. Dependencies are one-way only: `app_composition -> control_plane -> domain -> platform`. +2. Lateral direct dependencies are forbidden unless listed in `dependency_whitelist.md`. +3. Cross-domain communication must use events or Port interfaces; never include another domain's `internal/*.h`. +4. Each component keeps exactly one public facade header in `include/`; private headers stay in `internal/` via `PRIV_INCLUDE_DIRS`. + - Long-term canonical facade headers in this repo: + - `platform/include/platform.h` + - `domain/include/domain.h` + - `control_plane/include/control_plane.h` + - `app_composition/include/app_composition.h` +5. Upper layers may include only immediate downstream public facade headers; leapfrog includes across multiple layers are forbidden. +6. Cross-cutting contracts must have a single declared owner layer and one public declaration point; duplicated declarations across layers are forbidden. +7. Runtime state must have a single source of truth (SSOT); orchestration layers should query/subscribe rather than duplicate lower-layer lifecycle or readiness state. +8. Blocking APIs must define timeout and idempotent semantics (no destructive background continuation after caller timeout). + +## Build, Flash, and Validation +Activate ESP-IDF v5.5.2 before running any `idf.py` command: +```bash +export PATH=/opt/homebrew/bin:$PATH +export IDF_PATH=/Users/moyyang/esp/v5.5.2/esp-idf +source $IDF_PATH/export.sh +``` +- `idf.py set-target esp32s3`: one-time target setup. +- `idf.py build`: compile and validate. +- `idf.py -p flash monitor`: flash and open serial monitor (`Ctrl+]` to exit). +- `idf.py menuconfig`: adjust project options. +- `idf.py fullclean && idf.py build`: clear stale artifacts. + +## Coding Style & Naming Conventions +- Use 4-space indentation and keep braces/function style consistent with existing `components/*/*.c`. +- Prefer `lower_snake_case` for functions and variables; use module-prefixed public APIs. +- Use `UPPER_SNAKE_CASE` for macros/constants (`CMD_SEND_DATA`, `WIFI_CONNECTED_BIT`). +- Prefix file-local statics with `s_` (for example `s_server`, `s_jobs`) and keep per-file `TAG` logging constants. + +## Testing Guidelines +There is no dedicated unit-test directory currently. Minimum validation: +- Build check: `idf.py build`. +- Device smoke test after flash: `/v1/health`, printer connect/disconnect, and one print flow (text or image) via `curl`. +- For Control Plane or REST changes, include one request/response or lifecycle scenario in PR notes. + +## Commit & Pull Request Guidelines +Use a clear conventional format: +- Commit style: `feat(rest): add label offset endpoint`, `fix(wifi): handle STA timeout`. +- Keep commits focused and atomic by layer/module (`platform`, `domain`, `control_plane`, `app_composition`). +- PRs include purpose, affected layer(s), whitelist changes (if any), config changes, and validation evidence. + +## Security & Configuration Tips +- Never hardcode credentials or API keys in source files; configure through `menuconfig`. +- Do not commit local `sdkconfig` variants, serial-port-specific commands, or generated `build/` artifacts. diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..1497b6f --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,3 @@ +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) +project(TQ_printer_controller) diff --git a/README.md b/README.md new file mode 100644 index 0000000..1a4b0b7 --- /dev/null +++ b/README.md @@ -0,0 +1,374 @@ +# ESP32-S3 TQ Printer Controller (Wi-Fi REST API) + +ESP32-S3 works as a Wi-Fi REST controller and replaces Android App logic: +- REST client -> ESP32-S3 (`esp_http_server`) +- ESP32-S3 -> BLE printer (`TQPrinter` / `lyfPrinter`, `FFF2` write / `FFF1` notify) +- Command compatibility: + - Print path: `0x00~0x07` + - OTA path: `0xA0~0xA4` + +## Features + +- Wi-Fi STA-only mode (configured SSID/password; no SoftAP fallback) +- Built-in web UI at `/` for connect/status, text print, and Z-Image prompt print +- BLE central client auto-scan/connect to printer name +- Async print queue with jobs (`queued/running/success/failed/canceled`) +- Printer precheck (paper / battery / temperature) +- Built-in UTF-8 text rendering with Chinese support (GB2312 character set, 16x16 bitmap) +- Tap2talk multimodal voice interaction over DashScope WebSocket: + - ES8311 microphone/speaker via `esp_codec_dev` + - raw-opus uplink/downlink via `esp_audio_codec` + - WebSocket transport via `esp_websocket_client` +- Android-compatible print flow: + - `0x00` power on + - `0x03` set print param + - `0x04` chunked raster send + ACK + - `0x00` power off + - `0x02` feed paper +- REST APIs: + - Health/connection: + - `GET /v1/health` + - `POST /v1/printer/connect` + - `POST /v1/printer/disconnect` + - `GET /v1/printer/status` + - Print: + - `POST /v1/print/raster` + - `POST /v1/print/image` (JSON prompt -> generate image -> print, also compatible with direct PNG binary upload) + - `POST /v1/print/qr` + - `POST /v1/print/text` + - `POST /v1/print/receipt` + - `POST /v1/print/label` + - Jobs: + - `GET /v1/jobs` + - `DELETE /v1/jobs` + - `GET /v1/jobs/{id}` + - `DELETE /v1/jobs/{id}` + - Label control: + - `POST /v1/label/gap_move` + - `GET /v1/label/offset` + - `POST /v1/label/offset` + - OTA: + - `GET /v1/ota/version` + - `POST /v1/ota/jump_boot` + - `POST /v1/ota/jump_app` + - `POST /v1/ota/erase_page` + - `POST /v1/ota/write_frame` + - `POST /v1/ota/upgrade` + - Voice: + - `GET /v1/voice/status` + - `POST /v1/voice/session/start` + - `POST /v1/voice/session/stop` + - `POST /v1/voice/tap/start` + - `POST /v1/voice/tap/cancel` + +## Build + +Prerequisites: +- ESP-IDF v5.x +- ESP32-S3 board + +```bash +cd ai_printer +idf.py set-target esp32s3 +idf.py menuconfig +idf.py build +``` + +## Config + +In `menuconfig -> TQ Controller Config`: +- `TQ_WIFI_SSID` +- `TQ_WIFI_PASSWORD` +- `TQ_HTTP_PORT` +- `TQ_API_KEY` (optional) +- Z-Image HTTP auth and model 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 WebSocket auth and app fields: + - `TQ_VOICE_API_KEY` + - `TQ_VOICE_WORKSPACE_ID` + - `TQ_VOICE_APP_ID` +- Voice audio and codec fields: + - `TQ_VOICE_SAMPLE_RATE` + - `TQ_VOICE_OPUS_FRAME_MS` + - `TQ_VOICE_OPUS_BITRATE_KBPS` + - `TQ_VOICE_I2C_*` / `TQ_VOICE_I2S_*` + - `TQ_VOICE_CODEC_*` +- Board GPIO map fields: + - `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) + +When `TQ_API_KEY` is not empty, each request must include: + +```text +X-API-Key: +``` + +STA-only behavior: +- If SSID is empty, startup fails. +- If STA connect fails, startup fails (no AP fallback). + +## Flash + +```bash +cd ai_printer +idf.py -p /dev/tty.usbmodemXXXX flash monitor +``` + +## Web UI + +Open the controller IP in a browser: + +```text +http:/// +``` + +The page provides: +- health/status check +- connect/disconnect printer +- submit a simple text print job +- input an image prompt, then let ESP32-S3 call DashScope Z-Image, download PNG, decode/threshold/scale/raster conversion, and print +- view jobs list + +If API key is enabled, input it in the page before invoking actions. + +## REST Examples + +### Health +```bash +curl http:///v1/health +``` + +### Connect printer +```bash +curl -X POST http:///v1/printer/connect \ + -H 'Content-Type: application/json' \ + -d '{"name":"TQPrinter","timeout_ms":15000}' +# Legacy device name is also supported: +# -d '{"name":"lyfPrinter","timeout_ms":15000}' +``` + +Auto-match a compatible printer (by BLE service `0xFFF0`): + +```bash +curl -X POST http:///v1/printer/connect \ + -H 'Content-Type: application/json' \ + -d '{"name":"*","timeout_ms":20000}' +``` + +### Raster print +```bash +curl -X POST http:///v1/print/raster \ + -H 'Content-Type: application/json' \ + -d '{ + "width":384, + "height":200, + "density":"中等", + "encoding":"base64_msb_1bpp", + "data":"" + }' +``` + +### Image print (generate with prompt, then print) +```bash +curl -X POST http:///v1/print/image \ + -H 'Content-Type: application/json' \ + -d '{ + "prompt":"一只坐在窗边的橘猫,午后阳光,胶片质感,写实风格。", + "size":"1120*1440", + "prompt_extend":false, + "threshold":160, + "max_height":2200, + "scale_to_width":true, + "invert":false, + "density":"中等", + "timeout_ms":45000, + "fetch_timeout_ms":15000 + }' +``` + +### Image print (direct PNG upload, backward-compatible) +```bash +curl -X POST 'http:///v1/print/image?scale_to_width=1&threshold=160&invert=0&max_height=2200&density=medium' \ + -H 'Content-Type: image/png' \ + --data-binary @./sample.png +``` + +Request constraints: +- Request body limit: 4 MB +- Suggested image size: <= 3 MB when using direct PNG upload compatibility mode + +### QR print +```bash +curl -X POST http:///v1/print/qr \ + -H 'Content-Type: application/json' \ + -d '{ + "text":"https://example.com/pay/123", + "ecc":"H", + "module_scale":0, + "margin_modules":2, + "density":"中等" + }' +``` + +### Text print +```bash +curl -X POST http:///v1/print/text \ + -H 'Content-Type: application/json' \ + -d '{ + "text":"欢迎使用TQ打印机\\n订单号: A1024\\n谢谢惠顾", + "density":"中等", + "scale":2, + "line_spacing":2, + "max_height":1800 + }' +``` + +### Receipt print +```bash +curl -X POST http:///v1/print/receipt \ + -H 'Content-Type: application/json' \ + -d '{ + "title":"TQ FOOD", + "density":"中等", + "footer":"Thanks!", + "items":[ + {"name":"DishA","qty":2,"price":12.5}, + {"name":"DishB","qty":1,"price":8.0} + ] + }' +``` + +### Label print (with optional gap/offset) +```bash +curl -X POST http:///v1/print/label \ + -H 'Content-Type: application/json' \ + -d '{ + "width":384, + "height":260, + "encoding":"base64_msb_1bpp", + "data":"", + "gap_move_before":true, + "offset_tenths_mm":128, + "density":"中等" + }' +``` + +### Jobs +```bash +curl http:///v1/jobs +curl http:///v1/jobs/1 +curl -X DELETE http:///v1/jobs/1 +curl -X DELETE http:///v1/jobs -d '{"include_success":true,"include_failed":true,"include_canceled":true}' +``` + +### Label control +```bash +curl -X POST http:///v1/label/gap_move +curl http:///v1/label/offset +curl -X POST http:///v1/label/offset \ + -H 'Content-Type: application/json' \ + -d '{"offset_tenths_mm":128}' +``` + +### OTA primitives +```bash +curl http:///v1/ota/version +curl -X POST http:///v1/ota/jump_boot +curl -X POST http:///v1/ota/erase_page -H 'Content-Type: application/json' -d '{"page_num":0}' +curl -X POST http:///v1/ota/write_frame -H 'Content-Type: application/json' -d '{"packet_num":0,"is_last_frame":false,"data":""}' +curl -X POST http:///v1/ota/jump_app +``` + +### OTA full upgrade +```bash +curl -X POST http:///v1/ota/upgrade \ + -H 'Content-Type: application/json' \ + -d '{ + "firmware":"", + "jump_boot":true, + "jump_app":true, + "page_size":1024, + "packet_size":236, + "timeout_ms_per_step":5000 + }' +``` + +### Voice tap2talk +Start session: + +```bash +curl -X POST http:///v1/voice/session/start +``` + +Start one tap2talk round: + +```bash +curl -X POST http:///v1/voice/tap/start +``` + +Cancel current tap2talk round: + +```bash +curl -X POST http:///v1/voice/tap/cancel +``` + +Get voice status: + +```bash +curl http:///v1/voice/status +``` + +Stop session: + +```bash +curl -X POST http:///v1/voice/session/stop +``` + +## Notes + +- BLE side is central/client role, not printer peripheral role. +- `base64_msb_1bpp` uses Android-compatible bit order (MSB first). +- `/v1/print/image` supports two modes: JSON prompt generation (DashScope Z-Image) and raw `image/png` upload (no base64 wrapper). +- Large buffers for image upload/decode prefer PSRAM first, then fallback to internal RAM. +- Partition table uses `partitions.csv` with a 4MB `factory` app partition on 16MB flash modules. +- `/v1/print/text` and `/v1/print/receipt` now support UTF-8 Chinese via embedded 16x16 GB2312 glyphs. +- Characters outside embedded glyph set are rendered as square fallback boxes. +- QR encoding uses embedded `qrcodegen` (Project Nayuki C implementation). +- Voice flow is now single-round: audio uplink stops after `SpeechEnded`, then `LocalRespondingEnded` and `Stop` are sent after local playback drain. +- Web UI blocks starting the next voice round while voice is Thinking/Responding, marker image generation is running, or printer queue is still busy. + +## 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 +``` diff --git a/components/app_composition/CMakeLists.txt b/components/app_composition/CMakeLists.txt new file mode 100644 index 0000000..88257ec --- /dev/null +++ b/components/app_composition/CMakeLists.txt @@ -0,0 +1,10 @@ +idf_component_register( + SRCS + "src/app_main.c" + INCLUDE_DIRS + "include" + PRIV_INCLUDE_DIRS + "internal" + REQUIRES + control_plane +) diff --git a/components/app_composition/README.md b/components/app_composition/README.md new file mode 100644 index 0000000..13f019e --- /dev/null +++ b/components/app_composition/README.md @@ -0,0 +1,8 @@ +# App Composition Layer + +Purpose: top-level assembly only. + +Rules: +- `app_main` wires components, startup order, and shutdown hooks. +- No feature/business logic in composition code. +- No direct hardware operations outside platform abstractions. diff --git a/components/app_composition/include/.gitkeep b/components/app_composition/include/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/app_composition/include/app_composition.h b/components/app_composition/include/app_composition.h new file mode 100644 index 0000000..a278028 --- /dev/null +++ b/components/app_composition/include/app_composition.h @@ -0,0 +1,13 @@ +#pragma once + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +esp_err_t app_composition_start(void); + +#ifdef __cplusplus +} +#endif diff --git a/components/app_composition/internal/.gitkeep b/components/app_composition/internal/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/app_composition/src/.gitkeep b/components/app_composition/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/app_composition/src/app_main.c b/components/app_composition/src/app_main.c new file mode 100644 index 0000000..9ecdbd5 --- /dev/null +++ b/components/app_composition/src/app_main.c @@ -0,0 +1,21 @@ +#include "app_composition.h" +#include "control_plane.h" + +#include "esp_err.h" +#include "esp_log.h" + +static const char *TAG = "app_main"; + +esp_err_t app_composition_start(void) { + return controller_lifecycle_start(); +} + +void app_main(void) { + esp_err_t rc = app_composition_start(); + if (rc != ESP_OK) { + ESP_LOGE(TAG, "Controller lifecycle start failed: %s", esp_err_to_name(rc)); + return; + } + + ESP_LOGI(TAG, "TQ controller started"); +} diff --git a/components/control_plane/CMakeLists.txt b/components/control_plane/CMakeLists.txt new file mode 100644 index 0000000..5b35a3f --- /dev/null +++ b/components/control_plane/CMakeLists.txt @@ -0,0 +1,21 @@ +idf_component_register( + SRCS + "src/controller_lifecycle.c" + "src/rest_server.c" + "src/rest_server_common.c" + "src/rest_server_ops.c" + "src/rest_server_print.c" + "src/rest_server_print_image.c" + "src/rest_server_print_render.c" + "src/rest_server_jobs.c" + "src/rest_server_voice.c" + INCLUDE_DIRS + "include" + PRIV_INCLUDE_DIRS + "internal" + REQUIRES + domain + esp_http_server + json + mbedtls +) diff --git a/components/control_plane/README.md b/components/control_plane/README.md new file mode 100644 index 0000000..00acd56 --- /dev/null +++ b/components/control_plane/README.md @@ -0,0 +1,8 @@ +# Control Plane Layer + +Purpose: lifecycle, policy, health checks, retry/backoff, and orchestration decisions. + +Rules: +- Contains "decision + orchestration" only. +- Calls domain APIs; does not absorb hardware details. +- Maintains dependency whitelist decisions for exceptional lateral coupling. diff --git a/components/control_plane/include/.gitkeep b/components/control_plane/include/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/control_plane/include/control_plane.h b/components/control_plane/include/control_plane.h new file mode 100644 index 0000000..c3e7c64 --- /dev/null +++ b/components/control_plane/include/control_plane.h @@ -0,0 +1,37 @@ +#pragma once + +#include + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef enum { + CONTROLLER_LIFECYCLE_STATE_STOPPED = 0, + CONTROLLER_LIFECYCLE_STATE_STARTING, + CONTROLLER_LIFECYCLE_STATE_RUNNING, + CONTROLLER_LIFECYCLE_STATE_DEGRADED, + CONTROLLER_LIFECYCLE_STATE_STOPPING, +} controller_lifecycle_state_t; + +typedef struct { + controller_lifecycle_state_t state; + esp_err_t last_error; + uint32_t start_attempt; + int64_t last_transition_ms; + char last_stage[32]; +} controller_lifecycle_status_t; + +esp_err_t controller_lifecycle_start(void); +esp_err_t controller_lifecycle_stop(void); +void controller_lifecycle_get_status(controller_lifecycle_status_t *out_status); +const char *controller_lifecycle_state_str(controller_lifecycle_state_t state); + +esp_err_t rest_server_start(void); +void rest_server_stop(void); + +#ifdef __cplusplus +} +#endif diff --git a/components/control_plane/internal/.gitkeep b/components/control_plane/internal/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/control_plane/internal/rest_server_internal.h b/components/control_plane/internal/rest_server_internal.h new file mode 100644 index 0000000..be010f9 --- /dev/null +++ b/components/control_plane/internal/rest_server_internal.h @@ -0,0 +1,63 @@ +#pragma once + +#include +#include +#include + +#include "cJSON.h" +#include "esp_err.h" +#include "esp_http_server.h" + +bool rest_server_auth_ok(httpd_req_t *req); +esp_err_t rest_server_send_json(httpd_req_t *req, const char *status, cJSON *root); +esp_err_t rest_server_send_error(httpd_req_t *req, const char *status, const char *message); +esp_err_t rest_server_read_body(httpd_req_t *req, char **out_body); +bool rest_server_parse_uri_u32_tail(const char *uri, uint32_t *out_value); +esp_err_t rest_server_base64_decode_alloc(const char *b64, uint8_t **out_raw, size_t *out_len); +void rest_server_appendf(char *dst, size_t cap, size_t *offset, const char *fmt, ...); +bool rest_server_json_bool_with_default(cJSON *item, bool default_value); +esp_err_t rest_server_print_submit_raster_job_and_reply(httpd_req_t *req, + const uint8_t *raw, + size_t raw_len, + uint16_t width, + uint16_t height, + const char *density, + bool direct_ignore_precheck, + const char *warning, + const char *trace_id); + +esp_err_t rest_server_health_get(httpd_req_t *req); +esp_err_t rest_server_connect_post(httpd_req_t *req); +esp_err_t rest_server_disconnect_post(httpd_req_t *req); +esp_err_t rest_server_status_get(httpd_req_t *req); +esp_err_t rest_server_printer_direct_debug_get(httpd_req_t *req); +esp_err_t rest_server_printer_direct_debug_post(httpd_req_t *req); + +esp_err_t rest_server_print_raster_post(httpd_req_t *req); +esp_err_t rest_server_print_image_post(httpd_req_t *req); +esp_err_t rest_server_print_qr_post(httpd_req_t *req); +esp_err_t rest_server_print_label_post(httpd_req_t *req); +esp_err_t rest_server_print_text_post(httpd_req_t *req); +esp_err_t rest_server_print_receipt_post(httpd_req_t *req); + +esp_err_t rest_server_job_get(httpd_req_t *req); +esp_err_t rest_server_jobs_get(httpd_req_t *req); +esp_err_t rest_server_job_delete(httpd_req_t *req); +esp_err_t rest_server_jobs_delete(httpd_req_t *req); + +esp_err_t rest_server_label_gap_move_post(httpd_req_t *req); +esp_err_t rest_server_label_offset_get(httpd_req_t *req); +esp_err_t rest_server_label_offset_post(httpd_req_t *req); + +esp_err_t rest_server_ota_version_get(httpd_req_t *req); +esp_err_t rest_server_ota_jump_boot_post(httpd_req_t *req); +esp_err_t rest_server_ota_jump_app_post(httpd_req_t *req); +esp_err_t rest_server_ota_erase_page_post(httpd_req_t *req); +esp_err_t rest_server_ota_write_frame_post(httpd_req_t *req); +esp_err_t rest_server_ota_upgrade_post(httpd_req_t *req); + +esp_err_t rest_server_voice_status_get(httpd_req_t *req); +esp_err_t rest_server_voice_session_start_post(httpd_req_t *req); +esp_err_t rest_server_voice_session_stop_post(httpd_req_t *req); +esp_err_t rest_server_voice_tap_start_post(httpd_req_t *req); +esp_err_t rest_server_voice_tap_cancel_post(httpd_req_t *req); diff --git a/components/control_plane/src/.gitkeep b/components/control_plane/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/control_plane/src/controller_lifecycle.c b/components/control_plane/src/controller_lifecycle.c new file mode 100644 index 0000000..25bf147 --- /dev/null +++ b/components/control_plane/src/controller_lifecycle.c @@ -0,0 +1,310 @@ +#include "control_plane.h" + +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "domain.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" +#include "freertos/task.h" + +static const char *TAG = "controller_lifecycle"; +static SemaphoreHandle_t s_lock; +static controller_lifecycle_status_t s_status = { + .state = CONTROLLER_LIFECYCLE_STATE_STOPPED, + .last_error = ESP_OK, + .start_attempt = 0, + .last_transition_ms = 0, + .last_stage = "stopped", +}; + +static void lifecycle_lock_init_if_needed(void) { + if (s_lock == NULL) { + s_lock = xSemaphoreCreateMutex(); + } +} + +static bool lifecycle_lock_take(uint32_t timeout_ms) { + lifecycle_lock_init_if_needed(); + return s_lock != NULL && xSemaphoreTake(s_lock, pdMS_TO_TICKS(timeout_ms)) == pdTRUE; +} + +static void lifecycle_set_state_locked(controller_lifecycle_state_t state, + esp_err_t last_error, + const char *stage) { + s_status.state = state; + s_status.last_error = last_error; + s_status.last_transition_ms = esp_timer_get_time() / 1000; + strlcpy(s_status.last_stage, stage != NULL ? stage : "unknown", sizeof(s_status.last_stage)); + domain_diag_set_gauge(DOMAIN_DIAG_GAUGE_LIFECYCLE_STATE, (int32_t)state); +} + +const char *controller_lifecycle_state_str(controller_lifecycle_state_t state) { + switch (state) { + case CONTROLLER_LIFECYCLE_STATE_STOPPED: + return "stopped"; + case CONTROLLER_LIFECYCLE_STATE_STARTING: + return "starting"; + case CONTROLLER_LIFECYCLE_STATE_RUNNING: + return "running"; + case CONTROLLER_LIFECYCLE_STATE_DEGRADED: + return "degraded"; + case CONTROLLER_LIFECYCLE_STATE_STOPPING: + return "stopping"; + default: + return "unknown"; + } +} + +static esp_err_t lifecycle_start_system_runtime(void) { + return system_runtime_start(); +} + +static esp_err_t lifecycle_start_printer_protocol(void) { + return printer_protocol_init(); +} + +static esp_err_t lifecycle_start_voice(void) { + return voice_interaction_init(); +} + +static esp_err_t lifecycle_start_rest_server(void) { + return rest_server_start(); +} + +static esp_err_t lifecycle_stop_rest_server(void) { + rest_server_stop(); + return ESP_OK; +} + +static esp_err_t lifecycle_stop_voice(void) { + esp_err_t rc = voice_interaction_stop(NULL, 0); + if (rc == ESP_OK || rc == ESP_ERR_INVALID_STATE) { + return ESP_OK; + } + return rc; +} + +static esp_err_t lifecycle_stop_printer_protocol(void) { + esp_err_t rc = printer_protocol_stop(domain_policy_printer_stop_timeout_ms()); + if (rc == ESP_OK || rc == ESP_ERR_INVALID_STATE) { + return ESP_OK; + } + return rc; +} + +static esp_err_t lifecycle_stop_system_runtime(void) { + return system_runtime_shutdown(); +} + +typedef esp_err_t (*lifecycle_step_fn_t)(void); + +static esp_err_t lifecycle_run_step_with_retry(const char *stage, lifecycle_step_fn_t fn) { + uint32_t retry_count = domain_policy_lifecycle_start_retry_count(); + uint32_t max_attempts = retry_count + 1; + + for (uint32_t attempt = 0; attempt < max_attempts; ++attempt) { + esp_err_t rc = fn(); + if (rc == ESP_OK) { + if (attempt > 0) { + ESP_LOGW(TAG, "stage %s recovered after retries, attempt=%u", stage, (unsigned)(attempt + 1)); + } + return ESP_OK; + } + + bool can_retry = (attempt + 1 < max_attempts) && domain_policy_is_retryable_error(rc); + ESP_LOGW(TAG, + "stage %s failed, rc=0x%x, attempt=%u/%u, retry=%d", + stage, + (unsigned)rc, + (unsigned)(attempt + 1), + (unsigned)max_attempts, + can_retry ? 1 : 0); + + if (!can_retry) { + return rc; + } + + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_START_RETRY, 1); + vTaskDelay(pdMS_TO_TICKS(domain_policy_lifecycle_retry_backoff_ms(attempt))); + } + + return ESP_FAIL; +} + +esp_err_t controller_lifecycle_start(void) { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_START_ATTEMPT, 1); + + if (!lifecycle_lock_take(1000)) { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_START_FAILED, 1); + domain_diag_record_error("lifecycle_start", ESP_ERR_TIMEOUT, "lifecycle lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (s_status.state == CONTROLLER_LIFECYCLE_STATE_RUNNING) { + xSemaphoreGive(s_lock); + return ESP_OK; + } + if (s_status.state == CONTROLLER_LIFECYCLE_STATE_STARTING || + s_status.state == CONTROLLER_LIFECYCLE_STATE_STOPPING) { + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + s_status.start_attempt++; + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_STARTING, ESP_OK, "bootstrap"); + xSemaphoreGive(s_lock); + + bool system_started = false; + bool printer_started = false; + bool voice_started = false; + bool rest_started = false; + const char *failed_stage = "unknown"; + + failed_stage = "system_runtime"; + esp_err_t rc = lifecycle_run_step_with_retry("system_runtime", lifecycle_start_system_runtime); + if (rc != ESP_OK) { + goto start_failed; + } + system_started = true; + + failed_stage = "printer_protocol"; + rc = lifecycle_run_step_with_retry("printer_protocol", lifecycle_start_printer_protocol); + if (rc != ESP_OK) { + goto start_failed; + } + printer_started = true; + + failed_stage = "voice_interaction"; + rc = lifecycle_run_step_with_retry("voice_interaction", lifecycle_start_voice); + if (rc != ESP_OK) { + goto start_failed; + } + voice_started = true; + + failed_stage = "rest_server"; + rc = lifecycle_run_step_with_retry("rest_server", lifecycle_start_rest_server); + if (rc != ESP_OK) { + goto start_failed; + } + rest_started = true; + + image_generation_schedule_prewarm(); + + if (lifecycle_lock_take(1000)) { + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_RUNNING, ESP_OK, "running"); + xSemaphoreGive(s_lock); + } + + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_START_SUCCESS, 1); + ESP_LOGI(TAG, "controller lifecycle started"); + return ESP_OK; + +start_failed: + if (rest_started) { + (void)lifecycle_stop_rest_server(); + } + if (voice_started) { + (void)lifecycle_stop_voice(); + } + if (printer_started) { + (void)lifecycle_stop_printer_protocol(); + } + if (system_started) { + (void)lifecycle_stop_system_runtime(); + } + + if (lifecycle_lock_take(1000)) { + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_DEGRADED, rc, failed_stage); + xSemaphoreGive(s_lock); + } + + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_START_FAILED, 1); + domain_diag_record_error("lifecycle_start", rc, failed_stage); + ESP_LOGE(TAG, + "controller lifecycle start failed at stage=%s, rc=0x%x", + failed_stage, + (unsigned)rc); + return rc; +} + +esp_err_t controller_lifecycle_stop(void) { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_ATTEMPT, 1); + + if (!lifecycle_lock_take(1000)) { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_FAILED, 1); + domain_diag_record_error("lifecycle_stop", ESP_ERR_TIMEOUT, "lifecycle lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (s_status.state == CONTROLLER_LIFECYCLE_STATE_STOPPED) { + xSemaphoreGive(s_lock); + return ESP_OK; + } + if (s_status.state == CONTROLLER_LIFECYCLE_STATE_STARTING || + s_status.state == CONTROLLER_LIFECYCLE_STATE_STOPPING) { + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_STOPPING, ESP_OK, "stopping"); + xSemaphoreGive(s_lock); + + esp_err_t first_err = ESP_OK; + + esp_err_t rc = lifecycle_stop_rest_server(); + if (rc != ESP_OK && first_err == ESP_OK) { + first_err = rc; + } + + rc = lifecycle_stop_voice(); + if (rc != ESP_OK && first_err == ESP_OK) { + first_err = rc; + } + + rc = lifecycle_stop_printer_protocol(); + if (rc != ESP_OK && first_err == ESP_OK) { + first_err = rc; + } + + rc = lifecycle_stop_system_runtime(); + if (rc != ESP_OK && first_err == ESP_OK) { + first_err = rc; + } + + if (lifecycle_lock_take(1000)) { + if (first_err == ESP_OK) { + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_STOPPED, ESP_OK, "stopped"); + } else { + lifecycle_set_state_locked(CONTROLLER_LIFECYCLE_STATE_DEGRADED, first_err, "stop_failed"); + } + xSemaphoreGive(s_lock); + } + + if (first_err == ESP_OK) { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_SUCCESS, 1); + ESP_LOGI(TAG, "controller lifecycle stopped"); + } else { + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_FAILED, 1); + domain_diag_record_error("lifecycle_stop", first_err, "controller stop failed"); + ESP_LOGE(TAG, "controller lifecycle stop failed, rc=0x%x", (unsigned)first_err); + } + + return first_err; +} + +void controller_lifecycle_get_status(controller_lifecycle_status_t *out_status) { + if (out_status == NULL) { + return; + } + + memset(out_status, 0, sizeof(*out_status)); + + if (!lifecycle_lock_take(200)) { + return; + } + + *out_status = s_status; + xSemaphoreGive(s_lock); +} diff --git a/components/control_plane/src/rest_server.c b/components/control_plane/src/rest_server.c new file mode 100644 index 0000000..85c9b84 --- /dev/null +++ b/components/control_plane/src/rest_server.c @@ -0,0 +1,1216 @@ +#include "control_plane.h" + +#include + +#include "rest_server_internal.h" +#include "esp_http_server.h" +#include "esp_log.h" + +static const char *TAG = "rest_server"; + +static httpd_handle_t s_server; + +static const char *s_web_index = + "\n" + "\n" + "\n" + " \n" + " \n" + " TQ Printer Controller\n" + " \n" + "\n" + "\n" + "
\n" + "

TQ Printer Controller

\n" + "

ESP32-S3 local control page. This page calls the onboard REST API directly.

\n" + "\n" + " \n" + " \n" + "\n" + "
\n" + " \n" + " \n" + " \n" + "
\n" + "\n" + " \n" + " \n" + " \n" + " \n" + "
\n" + " \n" + " \n" + " \n" + "
\n" + "\n" + " \n" + "
\n" + " \n" + "
\n" + "
纸张状态:未知
\n" + "
Backend: -, Connected: -, Transport: -, GPIO: -, Expect: -
\n" + "
\n" + " \n" + "
\n" + "
Only effective on Direct backend. Use for sensor bring-up/debug.
\n" + "\n" + " \n" + "
参数标签中的字段名与 /v1/printer/direct/debug 的 JSON 键保持一致。
\n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + "
\n" + "
\n" + "
\n" + " \n" + " \n" + " \n" + " \n" + " \n" + " \n" + "
\n" + "
override_* 参数填 0 表示不覆盖,恢复为运行时默认策略。
\n" + "
Auto Diagnose 使用低功耗测试图案;若点击后仍重启(Brownout),请先改善供电或降低热头功率。
\n" + "\n" + " \n" + " \n" + "
\n" + " \n" + "
\n" + "\n" + " \n" + " \n" + "
\n" + " \n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + " \n" + "
\n" + "
\n" + " \n" + " \n" + " \n" + " \n" + "
\n" + "
Submit prompt only: ESP32-S3 calls DashScope Z-Image, downloads PNG, rasterizes and prints.
\n" + "\n" + " \n" + "
\n" + " \n" + "
\n" + "
语音状态:初始化中
\n" + "
\n" + "
单击开始本轮语音输入;识别结束后自动停止上传,等待语音播报和打印完成。
\n" + "\n" + "
Tip: connect printer first, then submit print jobs.
\n" + "
Ready.
\n" + "
\n" + "\n" + " \n" + "\n" + "\n"; + +static esp_err_t index_get(httpd_req_t *req) { + httpd_resp_set_type(req, "text/html; charset=utf-8"); + httpd_resp_set_hdr(req, "Cache-Control", "no-store"); + return httpd_resp_send(req, s_web_index, HTTPD_RESP_USE_STRLEN); +} + +static esp_err_t favicon_get(httpd_req_t *req) { + httpd_resp_set_status(req, "204 No Content"); + return httpd_resp_send(req, NULL, 0); +} + +esp_err_t rest_server_start(void) { + if (s_server != NULL) { + return ESP_OK; + } + + httpd_config_t config = HTTPD_DEFAULT_CONFIG(); + config.server_port = CONFIG_TQ_HTTP_PORT; + config.uri_match_fn = httpd_uri_match_wildcard; + config.max_uri_handlers = 36; + config.stack_size = 10240; +#if CONFIG_FREERTOS_UNICORE + config.core_id = 0; +#else + config.core_id = 1; +#endif + + esp_err_t err = httpd_start(&s_server, &config); + if (err != ESP_OK) { + ESP_LOGE(TAG, "httpd_start failed: %s", esp_err_to_name(err)); + return err; + } + + httpd_uri_t index = { + .uri = "/", + .method = HTTP_GET, + .handler = index_get, + }; + httpd_register_uri_handler(s_server, &index); + + httpd_uri_t favicon = { + .uri = "/favicon.ico", + .method = HTTP_GET, + .handler = favicon_get, + }; + httpd_register_uri_handler(s_server, &favicon); + + httpd_uri_t health = { + .uri = "/v1/health", + .method = HTTP_GET, + .handler = rest_server_health_get, + }; + httpd_register_uri_handler(s_server, &health); + + httpd_uri_t connect = { + .uri = "/v1/printer/connect", + .method = HTTP_POST, + .handler = rest_server_connect_post, + }; + httpd_register_uri_handler(s_server, &connect); + + httpd_uri_t disconnect = { + .uri = "/v1/printer/disconnect", + .method = HTTP_POST, + .handler = rest_server_disconnect_post, + }; + httpd_register_uri_handler(s_server, &disconnect); + + httpd_uri_t status = { + .uri = "/v1/printer/status", + .method = HTTP_GET, + .handler = rest_server_status_get, + }; + httpd_register_uri_handler(s_server, &status); + + httpd_uri_t direct_debug_get_uri = { + .uri = "/v1/printer/direct/debug", + .method = HTTP_GET, + .handler = rest_server_printer_direct_debug_get, + }; + httpd_register_uri_handler(s_server, &direct_debug_get_uri); + + httpd_uri_t direct_debug_post_uri = { + .uri = "/v1/printer/direct/debug", + .method = HTTP_POST, + .handler = rest_server_printer_direct_debug_post, + }; + httpd_register_uri_handler(s_server, &direct_debug_post_uri); + + httpd_uri_t voice_status = { + .uri = "/v1/voice/status", + .method = HTTP_GET, + .handler = rest_server_voice_status_get, + }; + httpd_register_uri_handler(s_server, &voice_status); + + httpd_uri_t voice_session_start = { + .uri = "/v1/voice/session/start", + .method = HTTP_POST, + .handler = rest_server_voice_session_start_post, + }; + httpd_register_uri_handler(s_server, &voice_session_start); + + httpd_uri_t voice_session_stop = { + .uri = "/v1/voice/session/stop", + .method = HTTP_POST, + .handler = rest_server_voice_session_stop_post, + }; + httpd_register_uri_handler(s_server, &voice_session_stop); + + httpd_uri_t voice_tap_start = { + .uri = "/v1/voice/tap/start", + .method = HTTP_POST, + .handler = rest_server_voice_tap_start_post, + }; + httpd_register_uri_handler(s_server, &voice_tap_start); + + httpd_uri_t voice_tap_cancel = { + .uri = "/v1/voice/tap/cancel", + .method = HTTP_POST, + .handler = rest_server_voice_tap_cancel_post, + }; + httpd_register_uri_handler(s_server, &voice_tap_cancel); + + httpd_uri_t print_raster = { + .uri = "/v1/print/raster", + .method = HTTP_POST, + .handler = rest_server_print_raster_post, + }; + httpd_register_uri_handler(s_server, &print_raster); + + httpd_uri_t print_image = { + .uri = "/v1/print/image", + .method = HTTP_POST, + .handler = rest_server_print_image_post, + }; + httpd_register_uri_handler(s_server, &print_image); + + httpd_uri_t print_qr = { + .uri = "/v1/print/qr", + .method = HTTP_POST, + .handler = rest_server_print_qr_post, + }; + httpd_register_uri_handler(s_server, &print_qr); + + httpd_uri_t print_text = { + .uri = "/v1/print/text", + .method = HTTP_POST, + .handler = rest_server_print_text_post, + }; + httpd_register_uri_handler(s_server, &print_text); + + httpd_uri_t print_label = { + .uri = "/v1/print/label", + .method = HTTP_POST, + .handler = rest_server_print_label_post, + }; + httpd_register_uri_handler(s_server, &print_label); + + httpd_uri_t print_receipt = { + .uri = "/v1/print/receipt", + .method = HTTP_POST, + .handler = rest_server_print_receipt_post, + }; + httpd_register_uri_handler(s_server, &print_receipt); + + httpd_uri_t jobs = { + .uri = "/v1/jobs", + .method = HTTP_GET, + .handler = rest_server_jobs_get, + }; + httpd_register_uri_handler(s_server, &jobs); + + httpd_uri_t jobs_delete_uri = { + .uri = "/v1/jobs", + .method = HTTP_DELETE, + .handler = rest_server_jobs_delete, + }; + httpd_register_uri_handler(s_server, &jobs_delete_uri); + + httpd_uri_t job = { + .uri = "/v1/jobs/*", + .method = HTTP_GET, + .handler = rest_server_job_get, + }; + httpd_register_uri_handler(s_server, &job); + + httpd_uri_t job_delete_uri = { + .uri = "/v1/jobs/*", + .method = HTTP_DELETE, + .handler = rest_server_job_delete, + }; + httpd_register_uri_handler(s_server, &job_delete_uri); + + httpd_uri_t label_gap = { + .uri = "/v1/label/gap_move", + .method = HTTP_POST, + .handler = rest_server_label_gap_move_post, + }; + httpd_register_uri_handler(s_server, &label_gap); + + httpd_uri_t label_offset_get_uri = { + .uri = "/v1/label/offset", + .method = HTTP_GET, + .handler = rest_server_label_offset_get, + }; + httpd_register_uri_handler(s_server, &label_offset_get_uri); + + httpd_uri_t label_offset_post_uri = { + .uri = "/v1/label/offset", + .method = HTTP_POST, + .handler = rest_server_label_offset_post, + }; + httpd_register_uri_handler(s_server, &label_offset_post_uri); + + httpd_uri_t ota_version = { + .uri = "/v1/ota/version", + .method = HTTP_GET, + .handler = rest_server_ota_version_get, + }; + httpd_register_uri_handler(s_server, &ota_version); + + httpd_uri_t ota_jump_boot = { + .uri = "/v1/ota/jump_boot", + .method = HTTP_POST, + .handler = rest_server_ota_jump_boot_post, + }; + httpd_register_uri_handler(s_server, &ota_jump_boot); + + httpd_uri_t ota_jump_app = { + .uri = "/v1/ota/jump_app", + .method = HTTP_POST, + .handler = rest_server_ota_jump_app_post, + }; + httpd_register_uri_handler(s_server, &ota_jump_app); + + httpd_uri_t ota_erase_page = { + .uri = "/v1/ota/erase_page", + .method = HTTP_POST, + .handler = rest_server_ota_erase_page_post, + }; + httpd_register_uri_handler(s_server, &ota_erase_page); + + httpd_uri_t ota_write_frame = { + .uri = "/v1/ota/write_frame", + .method = HTTP_POST, + .handler = rest_server_ota_write_frame_post, + }; + httpd_register_uri_handler(s_server, &ota_write_frame); + + httpd_uri_t ota_upgrade = { + .uri = "/v1/ota/upgrade", + .method = HTTP_POST, + .handler = rest_server_ota_upgrade_post, + }; + httpd_register_uri_handler(s_server, &ota_upgrade); + + ESP_LOGI(TAG, "REST server started on port %d", CONFIG_TQ_HTTP_PORT); + return ESP_OK; +} + +void rest_server_stop(void) { + if (s_server != NULL) { + httpd_stop(s_server); + s_server = NULL; + } +} diff --git a/components/control_plane/src/rest_server_common.c b/components/control_plane/src/rest_server_common.c new file mode 100644 index 0000000..05953e5 --- /dev/null +++ b/components/control_plane/src/rest_server_common.c @@ -0,0 +1,187 @@ +#include "rest_server_internal.h" + +#include +#include +#include +#include +#include + +#include "esp_heap_caps.h" +#include "mbedtls/base64.h" +#include "domain.h" + +#define REST_SERVER_MAX_BODY_BYTES (4 * 1024 * 1024) + +static void *alloc_prefer_psram(size_t size) { + void *ptr = heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = malloc(size); + } + return ptr; +} + +static void *calloc_prefer_psram(size_t n, size_t size) { + void *ptr = heap_caps_calloc(n, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = calloc(n, size); + } + return ptr; +} +bool rest_server_auth_ok(httpd_req_t *req) { + if (strlen(CONFIG_TQ_API_KEY) == 0) { + return true; + } + + char buf[96] = {0}; + if (httpd_req_get_hdr_value_str(req, "X-API-Key", buf, sizeof(buf)) != ESP_OK) { + return false; + } + + return strcmp(buf, CONFIG_TQ_API_KEY) == 0; +} + +esp_err_t rest_server_send_json(httpd_req_t *req, const char *status, cJSON *root) { + char *text = cJSON_PrintUnformatted(root); + if (text == NULL) { + return httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, "json encode failed"); + } + + httpd_resp_set_type(req, "application/json"); + httpd_resp_set_status(req, status); + esp_err_t err = httpd_resp_sendstr(req, text); + cJSON_free(text); + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_REST_RESPONSES_TOTAL, 1); + return err; +} + +esp_err_t rest_server_send_error(httpd_req_t *req, const char *status, const char *message) { + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", false); + cJSON_AddStringToObject(root, "error", message != NULL ? message : "unknown"); + esp_err_t err = rest_server_send_json(req, status, root); + cJSON_Delete(root); + domain_diag_counter_add(DOMAIN_DIAG_COUNTER_REST_ERRORS_TOTAL, 1); + domain_diag_record_error("rest_api", ESP_FAIL, message != NULL ? message : "unknown"); + return err; +} + +esp_err_t rest_server_read_body(httpd_req_t *req, char **out_body) { + if (out_body == NULL) { + return ESP_ERR_INVALID_ARG; + } + + *out_body = NULL; + + if (req->content_len <= 0 || req->content_len > REST_SERVER_MAX_BODY_BYTES) { + return ESP_ERR_INVALID_SIZE; + } + + char *buf = (char *)calloc_prefer_psram(1, (size_t)req->content_len + 1); + if (buf == NULL) { + return ESP_ERR_NO_MEM; + } + + int received = 0; + while (received < req->content_len) { + int ret = httpd_req_recv(req, buf + received, req->content_len - received); + if (ret <= 0) { + free(buf); + return ESP_FAIL; + } + received += ret; + } + + *out_body = buf; + return ESP_OK; +} + +bool rest_server_parse_uri_u32_tail(const char *uri, uint32_t *out_value) { + if (uri == NULL || out_value == NULL) { + return false; + } + + const char *slash = strrchr(uri, '/'); + if (slash == NULL || *(slash + 1) == '\0') { + return false; + } + + errno = 0; + char *endptr = NULL; + unsigned long val = strtoul(slash + 1, &endptr, 10); + if (errno != 0 || endptr == slash + 1 || *endptr != '\0' || val > UINT32_MAX) { + return false; + } + + *out_value = (uint32_t)val; + return true; +} + +esp_err_t rest_server_base64_decode_alloc(const char *b64, uint8_t **out_raw, size_t *out_len) { + if (b64 == NULL || out_raw == NULL || out_len == NULL) { + return ESP_ERR_INVALID_ARG; + } + + *out_raw = NULL; + *out_len = 0; + + size_t decoded_len = 0; + int rc = mbedtls_base64_decode(NULL, + 0, + &decoded_len, + (const unsigned char *)b64, + strlen(b64)); + if (!(rc == 0 || rc == MBEDTLS_ERR_BASE64_BUFFER_TOO_SMALL)) { + return ESP_ERR_INVALID_ARG; + } + + uint8_t *buf = (uint8_t *)alloc_prefer_psram(decoded_len); + if (buf == NULL) { + return ESP_ERR_NO_MEM; + } + + rc = mbedtls_base64_decode(buf, + decoded_len, + &decoded_len, + (const unsigned char *)b64, + strlen(b64)); + if (rc != 0) { + free(buf); + return ESP_ERR_INVALID_ARG; + } + + *out_raw = buf; + *out_len = decoded_len; + return ESP_OK; +} + +void rest_server_appendf(char *dst, size_t cap, size_t *offset, const char *fmt, ...) { + if (dst == NULL || cap == 0 || offset == NULL || fmt == NULL || *offset >= cap) { + return; + } + + va_list ap; + va_start(ap, fmt); + int n = vsnprintf(dst + *offset, cap - *offset, fmt, ap); + va_end(ap); + + if (n <= 0) { + return; + } + + size_t written = (size_t)n; + if (written >= cap - *offset) { + *offset = cap - 1; + return; + } + *offset += written; +} + +bool rest_server_json_bool_with_default(cJSON *item, bool default_value) { + if (item == NULL) { + return default_value; + } + if (cJSON_IsBool(item)) { + return cJSON_IsTrue(item); + } + return default_value; +} diff --git a/components/control_plane/src/rest_server_jobs.c b/components/control_plane/src/rest_server_jobs.c new file mode 100644 index 0000000..3fdebc0 --- /dev/null +++ b/components/control_plane/src/rest_server_jobs.c @@ -0,0 +1,173 @@ +#include "rest_server_internal.h" + +#include + +#include "domain.h" +esp_err_t rest_server_job_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint32_t job_id = 0; + if (!rest_server_parse_uri_u32_tail(req->uri, &job_id)) { + return rest_server_send_error(req, "400 Bad Request", "invalid job id"); + } + + print_job_info_t info; + if (!printer_protocol_get_job(job_id, &info)) { + return rest_server_send_error(req, "404 Not Found", "job not found"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "job_id", info.id); + cJSON_AddStringToObject(root, "state", printer_protocol_job_state_str(info.state)); + cJSON_AddNumberToObject(root, "progress", info.progress); + cJSON_AddStringToObject(root, "density", info.density); + cJSON_AddNumberToObject(root, "width", info.width); + cJSON_AddNumberToObject(root, "height", info.height); + cJSON_AddNumberToObject(root, "data_len", (double)info.data_len); + cJSON_AddStringToObject(root, "error", info.error); + cJSON_AddNumberToObject(root, "created_ms", (double)info.created_ms); + cJSON_AddNumberToObject(root, "started_ms", (double)info.started_ms); + cJSON_AddNumberToObject(root, "finished_ms", (double)info.finished_ms); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_jobs_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + print_job_info_t jobs[16]; + size_t total_count = 0; + esp_err_t list_rc = printer_protocol_list_jobs(jobs, 16, &total_count); + if (list_rc != ESP_OK) { + return rest_server_send_error(req, "500 Internal Server Error", "list jobs failed"); + } + + size_t emit_count = total_count; + if (emit_count > 16) { + emit_count = 16; + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "total", (double)total_count); + cJSON_AddNumberToObject(root, "returned", (double)emit_count); + + cJSON *arr = cJSON_AddArrayToObject(root, "jobs"); + for (size_t i = 0; i < emit_count; ++i) { + cJSON *item = cJSON_CreateObject(); + cJSON_AddNumberToObject(item, "job_id", jobs[i].id); + cJSON_AddStringToObject(item, "state", printer_protocol_job_state_str(jobs[i].state)); + cJSON_AddNumberToObject(item, "progress", jobs[i].progress); + cJSON_AddStringToObject(item, "density", jobs[i].density); + cJSON_AddNumberToObject(item, "width", jobs[i].width); + cJSON_AddNumberToObject(item, "height", jobs[i].height); + cJSON_AddNumberToObject(item, "data_len", (double)jobs[i].data_len); + cJSON_AddStringToObject(item, "error", jobs[i].error); + cJSON_AddNumberToObject(item, "created_ms", (double)jobs[i].created_ms); + cJSON_AddNumberToObject(item, "started_ms", (double)jobs[i].started_ms); + cJSON_AddNumberToObject(item, "finished_ms", (double)jobs[i].finished_ms); + cJSON_AddItemToArray(arr, item); + } + + if (total_count > emit_count) { + cJSON_AddStringToObject(root, "warning", "job list truncated"); + } + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_job_delete(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint32_t job_id = 0; + if (!rest_server_parse_uri_u32_tail(req->uri, &job_id)) { + return rest_server_send_error(req, "400 Bad Request", "invalid job id"); + } + + char cancel_err[128] = {0}; + esp_err_t cancel_rc = printer_protocol_cancel_job(job_id, cancel_err, sizeof(cancel_err)); + if (cancel_rc == ESP_ERR_NOT_FOUND) { + return rest_server_send_error(req, "404 Not Found", "job not found"); + } + if (cancel_rc == ESP_ERR_INVALID_STATE) { + return rest_server_send_error(req, + "409 Conflict", + cancel_err[0] != '\0' ? cancel_err : "job already finished"); + } + if (cancel_rc != ESP_OK) { + return rest_server_send_error(req, + "409 Conflict", + cancel_err[0] != '\0' ? cancel_err : "cancel failed"); + } + + print_job_info_t info; + bool ok = printer_protocol_get_job(job_id, &info); + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "job_id", job_id); + if (ok) { + cJSON_AddStringToObject(root, "state", printer_protocol_job_state_str(info.state)); + cJSON_AddStringToObject(root, "error", info.error); + } else { + cJSON_AddStringToObject(root, "state", "canceled"); + } + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_jobs_delete(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + bool include_success = true; + bool include_failed = true; + bool include_canceled = true; + + if (req->content_len > 0) { + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + include_success = rest_server_json_bool_with_default(cJSON_GetObjectItemCaseSensitive(json, "include_success"), true); + include_failed = rest_server_json_bool_with_default(cJSON_GetObjectItemCaseSensitive(json, "include_failed"), true); + include_canceled = rest_server_json_bool_with_default(cJSON_GetObjectItemCaseSensitive(json, "include_canceled"), true); + cJSON_Delete(json); + } + + size_t removed = printer_protocol_cleanup_jobs(include_success, include_failed, include_canceled); + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "removed", (double)removed); + cJSON_AddBoolToObject(root, "include_success", include_success); + cJSON_AddBoolToObject(root, "include_failed", include_failed); + cJSON_AddBoolToObject(root, "include_canceled", include_canceled); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + diff --git a/components/control_plane/src/rest_server_ops.c b/components/control_plane/src/rest_server_ops.c new file mode 100644 index 0000000..7a2c773 --- /dev/null +++ b/components/control_plane/src/rest_server_ops.c @@ -0,0 +1,807 @@ +#include "rest_server_internal.h" + +#include +#include +#include +#include + +#include "control_plane.h" +#include "domain.h" + +static const char *printer_backend_str(printer_backend_t backend) { + switch (backend) { + case PRINTER_BACKEND_BLE: + return "ble"; + case PRINTER_BACKEND_DIRECT: + return "direct"; + default: + return "unknown"; + } +} + +static bool parse_printer_backend(const cJSON *json, printer_backend_t *out_backend) { + if (json == NULL || out_backend == NULL) { + return false; + } + cJSON *jbackend = cJSON_GetObjectItemCaseSensitive((cJSON *)json, "backend"); + if (!cJSON_IsString(jbackend) || jbackend->valuestring == NULL) { + return false; + } + if (strcasecmp(jbackend->valuestring, "ble") == 0) { + *out_backend = PRINTER_BACKEND_BLE; + return true; + } + if (strcasecmp(jbackend->valuestring, "direct") == 0) { + *out_backend = PRINTER_BACKEND_DIRECT; + return true; + } + return false; +} + +static void fill_runtime_diag_json(cJSON *root) { + domain_diag_snapshot_t snapshot = {0}; + domain_diag_get_snapshot(&snapshot); + + cJSON *diag = cJSON_AddObjectToObject(root, "diagnostics"); + if (diag == NULL) { + return; + } + + cJSON *counters = cJSON_AddObjectToObject(diag, "counters"); + if (counters != NULL) { + for (int i = 0; i < DOMAIN_DIAG_COUNTER_MAX; ++i) { + cJSON_AddNumberToObject(counters, + domain_diag_counter_name((domain_diag_counter_t)i), + (double)snapshot.counters[i]); + } + } + + cJSON *gauges = cJSON_AddObjectToObject(diag, "gauges"); + if (gauges != NULL) { + for (int i = 0; i < DOMAIN_DIAG_GAUGE_MAX; ++i) { + cJSON_AddNumberToObject(gauges, + domain_diag_gauge_name((domain_diag_gauge_t)i), + snapshot.gauges[i]); + } + } + + cJSON *last_error = cJSON_AddObjectToObject(diag, "last_error"); + if (last_error != NULL) { + cJSON_AddNumberToObject(last_error, "ts_ms", (double)snapshot.last_error_ms); + cJSON_AddNumberToObject(last_error, "code", (double)snapshot.last_error_code); + cJSON_AddStringToObject(last_error, "source", snapshot.last_error_source); + cJSON_AddStringToObject(last_error, "message", snapshot.last_error_message); + } +} + +static void fill_runtime_json(cJSON *root) { + char ip[32] = {0}; + system_runtime_get_ip(ip, sizeof(ip)); + + printer_runtime_status_t st = {0}; + printer_protocol_get_runtime_status(&st); + + cJSON_AddBoolToObject(root, "wifi_ready", system_runtime_wifi_ready()); + cJSON_AddStringToObject(root, "wifi_mode", "sta"); + cJSON_AddStringToObject(root, "ip", ip); + + cJSON_AddStringToObject(root, "printer_backend", printer_backend_str(st.backend)); + cJSON_AddBoolToObject(root, "printer_connected", st.connected); + cJSON_AddBoolToObject(root, "printer_transport_ready", st.transport_ready); + cJSON_AddBoolToObject(root, "ble_connected", st.backend == PRINTER_BACKEND_BLE && st.connected); + cJSON_AddBoolToObject(root, "ble_notify_ready", st.backend == PRINTER_BACKEND_BLE && st.notify_ready); + cJSON_AddBoolToObject(root, "printer_busy", st.busy); + cJSON_AddBoolToObject(root, "has_paper", st.has_paper); + cJSON_AddNumberToObject(root, "paper_gpio_level", st.paper_gpio_level); + cJSON_AddNumberToObject(root, "paper_present_level", st.paper_present_level); + cJSON_AddNumberToObject(root, "battery_percent", st.battery_percent); + cJSON_AddNumberToObject(root, "temperature", st.temperature); + cJSON_AddBoolToObject(root, "supports_gap_move", st.supports_gap_move); + cJSON_AddBoolToObject(root, "supports_label_offset", st.supports_label_offset); + cJSON_AddBoolToObject(root, "supports_ota", st.supports_ota); + cJSON_AddNumberToObject(root, "queue_depth", st.queue_depth); + cJSON_AddNumberToObject(root, "mtu", st.mtu); + cJSON_AddNumberToObject(root, "last_status_ms", (double)st.last_status_ms); + + voice_interaction_status_t voice = {0}; + voice_interaction_get_status(&voice); + cJSON_AddBoolToObject(root, "voice_ready", voice.ready); + cJSON_AddBoolToObject(root, "voice_session_active", voice.session_active); + cJSON_AddBoolToObject(root, "voice_ws_connected", voice.ws_connected); + cJSON_AddBoolToObject(root, "voice_started", voice.started); + cJSON_AddBoolToObject(root, "voice_tap_active", voice.tap_active); + cJSON_AddStringToObject(root, + "voice_dialog_state", + voice_interaction_dialog_state_str(voice.dialog_state)); + cJSON_AddStringToObject(root, "voice_task_id", voice.task_id); + cJSON_AddStringToObject(root, "voice_dialog_id", voice.dialog_id); + cJSON_AddStringToObject(root, "voice_last_error", voice.last_error); + cJSON_AddNumberToObject(root, "voice_last_event_ms", (double)voice.last_event_ms); + cJSON_AddNumberToObject(root, "voice_upstream_packets", (double)voice.upstream_packets); + cJSON_AddNumberToObject(root, "voice_downstream_packets", (double)voice.downstream_packets); + + controller_lifecycle_status_t lifecycle = {0}; + controller_lifecycle_get_status(&lifecycle); + cJSON_AddStringToObject(root, "lifecycle_state", controller_lifecycle_state_str(lifecycle.state)); + cJSON_AddStringToObject(root, "lifecycle_stage", lifecycle.last_stage); + cJSON_AddNumberToObject(root, "lifecycle_last_error", (double)lifecycle.last_error); + cJSON_AddNumberToObject(root, "lifecycle_start_attempt", (double)lifecycle.start_attempt); + cJSON_AddNumberToObject(root, "lifecycle_last_transition_ms", (double)lifecycle.last_transition_ms); + + fill_runtime_diag_json(root); +} + +esp_err_t rest_server_health_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + cJSON *root = cJSON_CreateObject(); + controller_lifecycle_status_t lifecycle = {0}; + controller_lifecycle_get_status(&lifecycle); + bool healthy = (lifecycle.state == CONTROLLER_LIFECYCLE_STATE_RUNNING) && system_runtime_wifi_ready(); + cJSON_AddBoolToObject(root, "ok", healthy); + fill_runtime_json(root); + + esp_err_t err = rest_server_send_json(req, healthy ? "200 OK" : "503 Service Unavailable", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_connect_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + char name[32] = "TQPrinter"; + uint32_t timeout_ms = domain_policy_rest_printer_connect_timeout_ms(); + printer_backend_t backend = printer_protocol_get_backend(); + bool backend_specified = false; + + if (req->content_len > 0) { + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + if (json == NULL) { + free(body); + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jname = cJSON_GetObjectItemCaseSensitive(json, "name"); + if (cJSON_IsString(jname) && jname->valuestring != NULL) { + strlcpy(name, jname->valuestring, sizeof(name)); + } + + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + if (cJSON_IsNumber(jtimeout)) { + uint32_t min_ms = domain_policy_rest_printer_connect_timeout_min_ms(); + uint32_t max_ms = domain_policy_rest_printer_connect_timeout_max_ms(); + if (jtimeout->valuedouble >= (double)min_ms && jtimeout->valuedouble <= (double)max_ms) { + timeout_ms = (uint32_t)jtimeout->valuedouble; + } else { + cJSON_Delete(json); + free(body); + return rest_server_send_error(req, "400 Bad Request", "timeout_ms out of range"); + } + } + + cJSON *jbackend = cJSON_GetObjectItemCaseSensitive(json, "backend"); + if (jbackend != NULL) { + backend_specified = true; + if (!parse_printer_backend(json, &backend)) { + cJSON_Delete(json); + free(body); + return rest_server_send_error(req, "400 Bad Request", "backend must be ble or direct"); + } + } + + cJSON_Delete(json); + free(body); + } + + printer_connect_options_t opt = { + .backend = backend, + .name = backend == PRINTER_BACKEND_BLE ? name : NULL, + .timeout_ms = timeout_ms, + }; + char connect_err[96] = {0}; + esp_err_t err = printer_protocol_connect_ex(&opt, connect_err, sizeof(connect_err)); + if (err != ESP_OK) { + if (err == ESP_ERR_TIMEOUT) { + return rest_server_send_error(req, + "504 Gateway Timeout", + connect_err[0] != '\0' ? connect_err : "connect timeout"); + } + if (err == ESP_ERR_NOT_SUPPORTED || err == ESP_ERR_INVALID_STATE) { + return rest_server_send_error(req, + "409 Conflict", + connect_err[0] != '\0' ? connect_err : "connect failed"); + } + if (err == ESP_ERR_INVALID_ARG) { + return rest_server_send_error(req, + "400 Bad Request", + connect_err[0] != '\0' ? connect_err : "invalid connect params"); + } + return rest_server_send_error(req, + "500 Internal Server Error", + connect_err[0] != '\0' ? connect_err : "connect failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "connected"); + cJSON_AddStringToObject(root, "backend", printer_backend_str(backend)); + cJSON_AddBoolToObject(root, "backend_specified", backend_specified); + fill_runtime_json(root); + + err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_disconnect_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + printer_protocol_disconnect(); + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "disconnected"); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_status_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + fill_runtime_json(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +static void add_direct_debug_json_fields(cJSON *root, const printer_direct_debug_config_t *cfg) { + cJSON_AddNumberToObject(root, "shift_clock_high_us", cfg->shift_clock_high_us); + cJSON_AddNumberToObject(root, "shift_clock_low_us", cfg->shift_clock_low_us); + cJSON_AddNumberToObject(root, "latch_pulse_us", cfg->latch_pulse_us); + cJSON_AddBoolToObject(root, "strobe_active_high", cfg->strobe_active_high); + cJSON_AddBoolToObject(root, "boost_active_high", cfg->boost_active_high); + cJSON_AddNumberToObject(root, "override_strobe_on_us", cfg->override_strobe_on_us); + cJSON_AddNumberToObject(root, "override_strobe_interval_us", cfg->override_strobe_interval_us); + cJSON_AddNumberToObject(root, "override_motor_step_us", cfg->override_motor_step_us); + cJSON_AddNumberToObject(root, "override_steps_per_line", cfg->override_steps_per_line); +} + +static esp_err_t direct_debug_error_response(httpd_req_t *req, esp_err_t rc, const char *msg) { + if (rc == ESP_ERR_INVALID_ARG) { + return rest_server_send_error(req, "400 Bad Request", msg); + } + if (rc == ESP_ERR_NOT_SUPPORTED || rc == ESP_ERR_INVALID_STATE) { + return rest_server_send_error(req, "409 Conflict", msg); + } + if (rc == ESP_ERR_TIMEOUT) { + return rest_server_send_error(req, "504 Gateway Timeout", msg); + } + return rest_server_send_error(req, "500 Internal Server Error", msg); +} + +esp_err_t rest_server_printer_direct_debug_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + printer_direct_debug_config_t cfg = {0}; + char get_err[128] = {0}; + esp_err_t rc = printer_protocol_get_direct_debug_config(&cfg, get_err, sizeof(get_err)); + if (rc != ESP_OK) { + return direct_debug_error_response(req, + rc, + get_err[0] != '\0' ? get_err : "get direct debug failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "backend", printer_backend_str(printer_protocol_get_backend())); + add_direct_debug_json_fields(root, &cfg); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_printer_direct_debug_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + printer_direct_debug_config_t cfg = {0}; + char get_err[128] = {0}; + esp_err_t rc = printer_protocol_get_direct_debug_config(&cfg, get_err, sizeof(get_err)); + if (rc != ESP_OK) { + return direct_debug_error_response(req, + rc, + get_err[0] != '\0' ? get_err : "get direct debug failed"); + } + + bool reset_defaults = false; + bool has_update = false; + if (req->content_len > 0) { + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jreset = cJSON_GetObjectItemCaseSensitive(json, "reset_defaults"); + if (cJSON_IsBool(jreset)) { + reset_defaults = cJSON_IsTrue(jreset); + } + + cJSON *jshift_hi = cJSON_GetObjectItemCaseSensitive(json, "shift_clock_high_us"); + if (jshift_hi != NULL) { + if (!cJSON_IsNumber(jshift_hi) || jshift_hi->valuedouble < 1 || jshift_hi->valuedouble > 50) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "shift_clock_high_us must be 1..50"); + } + cfg.shift_clock_high_us = (uint16_t)jshift_hi->valuedouble; + has_update = true; + } + + cJSON *jshift_lo = cJSON_GetObjectItemCaseSensitive(json, "shift_clock_low_us"); + if (jshift_lo != NULL) { + if (!cJSON_IsNumber(jshift_lo) || jshift_lo->valuedouble < 1 || jshift_lo->valuedouble > 50) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "shift_clock_low_us must be 1..50"); + } + cfg.shift_clock_low_us = (uint16_t)jshift_lo->valuedouble; + has_update = true; + } + + cJSON *jlatch = cJSON_GetObjectItemCaseSensitive(json, "latch_pulse_us"); + if (jlatch != NULL) { + if (!cJSON_IsNumber(jlatch) || jlatch->valuedouble < 1 || jlatch->valuedouble > 50) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "latch_pulse_us must be 1..50"); + } + cfg.latch_pulse_us = (uint16_t)jlatch->valuedouble; + has_update = true; + } + + cJSON *jstb = cJSON_GetObjectItemCaseSensitive(json, "strobe_active_high"); + if (cJSON_IsBool(jstb)) { + cfg.strobe_active_high = cJSON_IsTrue(jstb); + has_update = true; + } + + cJSON *jboost = cJSON_GetObjectItemCaseSensitive(json, "boost_active_high"); + if (cJSON_IsBool(jboost)) { + cfg.boost_active_high = cJSON_IsTrue(jboost); + has_update = true; + } + + cJSON *jstrobe_on = cJSON_GetObjectItemCaseSensitive(json, "override_strobe_on_us"); + if (jstrobe_on != NULL) { + if (!cJSON_IsNumber(jstrobe_on) || jstrobe_on->valuedouble < 0 || jstrobe_on->valuedouble > 10000) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_strobe_on_us must be 0..10000"); + } + if (jstrobe_on->valuedouble > 0 && jstrobe_on->valuedouble < 100) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_strobe_on_us must be 0 or 100..10000"); + } + cfg.override_strobe_on_us = (uint16_t)jstrobe_on->valuedouble; + has_update = true; + } + + cJSON *jstrobe_gap = cJSON_GetObjectItemCaseSensitive(json, "override_strobe_interval_us"); + if (jstrobe_gap != NULL) { + if (!cJSON_IsNumber(jstrobe_gap) || jstrobe_gap->valuedouble < 0 || jstrobe_gap->valuedouble > 10000) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_strobe_interval_us must be 0..10000"); + } + cfg.override_strobe_interval_us = (uint16_t)jstrobe_gap->valuedouble; + has_update = true; + } + + cJSON *jmotor = cJSON_GetObjectItemCaseSensitive(json, "override_motor_step_us"); + if (jmotor != NULL) { + if (!cJSON_IsNumber(jmotor) || jmotor->valuedouble < 0 || jmotor->valuedouble > 20000) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_motor_step_us must be 0..20000"); + } + if (jmotor->valuedouble > 0 && jmotor->valuedouble < 100) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_motor_step_us must be 0 or 100..20000"); + } + cfg.override_motor_step_us = (uint16_t)jmotor->valuedouble; + has_update = true; + } + + cJSON *jsteps = cJSON_GetObjectItemCaseSensitive(json, "override_steps_per_line"); + if (jsteps != NULL) { + if (!cJSON_IsNumber(jsteps) || jsteps->valuedouble < 0 || jsteps->valuedouble > 8) { + cJSON_Delete(json); + return rest_server_send_error(req, + "400 Bad Request", + "override_steps_per_line must be 0..8"); + } + cfg.override_steps_per_line = (uint8_t)jsteps->valuedouble; + has_update = true; + } + + cJSON_Delete(json); + } + + char set_err[128] = {0}; + rc = printer_protocol_set_direct_debug_config(has_update ? &cfg : NULL, + reset_defaults, + set_err, + sizeof(set_err)); + if (rc != ESP_OK) { + return direct_debug_error_response(req, + rc, + set_err[0] != '\0' ? set_err : "set direct debug failed"); + } + + memset(&cfg, 0, sizeof(cfg)); + memset(get_err, 0, sizeof(get_err)); + rc = printer_protocol_get_direct_debug_config(&cfg, get_err, sizeof(get_err)); + if (rc != ESP_OK) { + return direct_debug_error_response(req, + rc, + get_err[0] != '\0' ? get_err : "get direct debug failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddBoolToObject(root, "reset_defaults", reset_defaults); + cJSON_AddBoolToObject(root, "updated", has_update); + cJSON_AddStringToObject(root, "backend", printer_backend_str(printer_protocol_get_backend())); + add_direct_debug_json_fields(root, &cfg); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_label_gap_move_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint32_t timeout_ms = domain_policy_rest_label_timeout_ms(); + if (req->content_len > 0) { + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + if (jtimeout != NULL) { + if (!cJSON_IsNumber(jtimeout) || + jtimeout->valuedouble < (double)domain_policy_rest_label_timeout_min_ms() || + jtimeout->valuedouble > (double)domain_policy_rest_label_timeout_max_ms()) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "timeout_ms out of range"); + } + timeout_ms = (uint32_t)jtimeout->valuedouble; + } + cJSON_Delete(json); + } + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_gap_move(timeout_ms, cmd_err, sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "gap move failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "gap move success"); + cJSON_AddNumberToObject(root, "timeout_ms", timeout_ms); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_label_offset_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint8_t offset = 0; + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_get_label_offset(&offset, + domain_policy_rest_label_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "get offset failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "offset_tenths_mm", offset); + cJSON_AddNumberToObject(root, "offset_mm", ((double)offset) / 10.0); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_label_offset_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jvalue = cJSON_GetObjectItemCaseSensitive(json, "offset_tenths_mm"); + if (!cJSON_IsNumber(jvalue) || jvalue->valuedouble < 0 || jvalue->valuedouble > 254) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "offset_tenths_mm must be 0..254"); + } + + uint8_t value = (uint8_t)jvalue->valuedouble; + cJSON_Delete(json); + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_set_label_offset(value, + domain_policy_rest_label_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "set offset failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "offset_tenths_mm", value); + cJSON_AddNumberToObject(root, "offset_mm", ((double)value) / 10.0); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_version_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + printer_ota_version_t version = {0}; + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_ota_get_version(&version, + domain_policy_rest_ota_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "get version failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "major", version.major); + cJSON_AddNumberToObject(root, "minor", version.minor); + cJSON_AddNumberToObject(root, "patch", version.patch); + char version_text[32]; + snprintf(version_text, sizeof(version_text), "V%u.%u.%u", version.major, version.minor, version.patch); + cJSON_AddStringToObject(root, "version", version_text); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_jump_boot_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_ota_jump_boot(domain_policy_rest_ota_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "jump boot failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "jumped to boot"); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_jump_app_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_ota_jump_app(domain_policy_rest_ota_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "jump app failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "jumped to app"); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_erase_page_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jpage = cJSON_GetObjectItemCaseSensitive(json, "page_num"); + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + if (!cJSON_IsNumber(jpage) || jpage->valuedouble < 0 || jpage->valuedouble > 65535) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "page_num must be 0..65535"); + } + + uint32_t timeout_ms = domain_policy_rest_ota_timeout_ms(); + if (jtimeout != NULL) { + if (!cJSON_IsNumber(jtimeout) || + jtimeout->valuedouble < (double)domain_policy_rest_ota_timeout_min_ms() || + jtimeout->valuedouble > (double)domain_policy_rest_ota_timeout_max_ms()) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "timeout_ms out of range"); + } + timeout_ms = (uint32_t)jtimeout->valuedouble; + } + + uint16_t page_num = (uint16_t)jpage->valuedouble; + cJSON_Delete(json); + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_ota_erase_page(page_num, timeout_ms, cmd_err, sizeof(cmd_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "erase page failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "page_num", page_num); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_write_frame_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jpack = cJSON_GetObjectItemCaseSensitive(json, "packet_num"); + cJSON *jlast = cJSON_GetObjectItemCaseSensitive(json, "is_last_frame"); + cJSON *jdata = cJSON_GetObjectItemCaseSensitive(json, "data"); + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + + if (!cJSON_IsNumber(jpack) || jpack->valuedouble < 0 || jpack->valuedouble > 65535 || + !cJSON_IsString(jdata) || jdata->valuestring == NULL) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "packet_num and data are required"); + } + + uint32_t timeout_ms = domain_policy_rest_ota_timeout_ms(); + if (jtimeout != NULL) { + if (!cJSON_IsNumber(jtimeout) || + jtimeout->valuedouble < (double)domain_policy_rest_ota_timeout_min_ms() || + jtimeout->valuedouble > (double)domain_policy_rest_ota_timeout_max_ms()) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "timeout_ms out of range"); + } + timeout_ms = (uint32_t)jtimeout->valuedouble; + } + bool is_last = rest_server_json_bool_with_default(jlast, false); + uint16_t packet_num = (uint16_t)jpack->valuedouble; + + uint8_t *frame_data = NULL; + size_t frame_len = 0; + esp_err_t b64_rc = rest_server_base64_decode_alloc(jdata->valuestring, &frame_data, &frame_len); + cJSON_Delete(json); + if (b64_rc != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid base64 data"); + } + + char cmd_err[128] = {0}; + esp_err_t rc = printer_protocol_ota_write_frame(packet_num, + is_last, + frame_data, + frame_len, + timeout_ms, + cmd_err, + sizeof(cmd_err)); + free(frame_data); + if (rc != ESP_OK) { + return rest_server_send_error(req, "409 Conflict", cmd_err[0] != '\0' ? cmd_err : "write frame failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "packet_num", packet_num); + cJSON_AddBoolToObject(root, "is_last_frame", is_last); + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_ota_upgrade_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + return rest_server_send_error(req, + "409 Conflict", + "bulk ota upgrade endpoint disabled; use jump/erase/write/version step APIs"); +} diff --git a/components/control_plane/src/rest_server_print.c b/components/control_plane/src/rest_server_print.c new file mode 100644 index 0000000..b664e86 --- /dev/null +++ b/components/control_plane/src/rest_server_print.c @@ -0,0 +1,135 @@ +#include "rest_server_internal.h" + +#include +#include + +#include "esp_log.h" +#include "domain.h" + +static const char *TAG = "rest_print"; + +static const char *trace_id_or_default(const char *trace_id) { + return (trace_id != NULL && trace_id[0] != '\0') ? trace_id : "-"; +} + +esp_err_t rest_server_print_submit_raster_job_and_reply(httpd_req_t *req, + const uint8_t *raw, + size_t raw_len, + uint16_t width, + uint16_t height, + const char *density, + bool direct_ignore_precheck, + const char *warning, + const char *trace_id) { + const char *trace = trace_id_or_default(trace_id); + ESP_LOGI(TAG, + "print submit start, trace=%s, raster_bytes=%u, size=%ux%u, density=%s, ignore_precheck=%d", + trace, + (unsigned)raw_len, + (unsigned)width, + (unsigned)height, + density != NULL ? density : "中等", + direct_ignore_precheck); + + char submit_err[128] = {0}; + uint32_t job_id = 0; + printer_print_options_t options = { + .direct_ignore_precheck = direct_ignore_precheck, + }; + esp_err_t submit_rc = printer_protocol_submit_raster_job_ex(raw, + raw_len, + width, + height, + density, + &options, + &job_id, + submit_err, + sizeof(submit_err)); + if (submit_rc != ESP_OK) { + ESP_LOGW(TAG, + "print submit failed, trace=%s, rc=0x%x, msg=%s", + trace, + (unsigned)submit_rc, + submit_err[0] != '\0' ? submit_err : "submit failed"); + return rest_server_send_error(req, + "400 Bad Request", + submit_err[0] != '\0' ? submit_err : "submit failed"); + } + + ESP_LOGI(TAG, "print submit done, trace=%s, job_id=%u", trace, (unsigned)job_id); + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddNumberToObject(root, "job_id", job_id); + cJSON_AddStringToObject(root, "state", "queued"); + cJSON_AddBoolToObject(root, "ignore_precheck", direct_ignore_precheck); + if (warning != NULL && warning[0] != '\0') { + cJSON_AddStringToObject(root, "warning", warning); + } + + esp_err_t err = rest_server_send_json(req, "202 Accepted", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_print_raster_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jwidth = cJSON_GetObjectItemCaseSensitive(json, "width"); + cJSON *jheight = cJSON_GetObjectItemCaseSensitive(json, "height"); + cJSON *jencoding = cJSON_GetObjectItemCaseSensitive(json, "encoding"); + cJSON *jdata = cJSON_GetObjectItemCaseSensitive(json, "data"); + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + if (!cJSON_IsNumber(jwidth) || !cJSON_IsNumber(jheight) || + !cJSON_IsString(jencoding) || !cJSON_IsString(jdata)) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "missing required fields"); + } + + if (strcmp(jencoding->valuestring, "base64_msb_1bpp") != 0) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "unsupported encoding"); + } + + const char *density = (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) + ? jdensity->valuestring + : "中等"; + bool direct_ignore_precheck = rest_server_json_bool_with_default(jignore, false); + + uint8_t *raw = NULL; + size_t raw_len = 0; + esp_err_t b64_rc = rest_server_base64_decode_alloc(jdata->valuestring, &raw, &raw_len); + if (b64_rc != ESP_OK) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "invalid base64"); + } + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raw, + raw_len, + (uint16_t)jwidth->valuedouble, + (uint16_t)jheight->valuedouble, + density, + direct_ignore_precheck, + NULL, + NULL); + free(raw); + cJSON_Delete(json); + return submit_rc; +} diff --git a/components/control_plane/src/rest_server_print_image.c b/components/control_plane/src/rest_server_print_image.c new file mode 100644 index 0000000..a28a6ef --- /dev/null +++ b/components/control_plane/src/rest_server_print_image.c @@ -0,0 +1,661 @@ +#include "rest_server_internal.h" + +#include +#include +#include +#include + +#include "esp_log.h" +#include "domain.h" + +static const char *TAG = "rest_print"; +#define SCREEN_PREVIEW_TIMEOUT_MS 200 + +typedef struct { + bool scale_to_width; + uint8_t threshold; + bool invert; + uint16_t max_height; + const char *density; + bool direct_ignore_precheck; +} image_print_options_t; + +typedef struct { + char prompt[801]; + char size[24]; + bool has_size; + bool prompt_extend; + bool has_seed; + uint32_t seed; + uint32_t timeout_ms; + uint32_t fetch_timeout_ms; +} image_generate_options_t; + +static bool parse_bool_text(const char *text, bool *out_value) { + if (text == NULL || out_value == NULL) { + return false; + } + if (strcmp(text, "1") == 0 || strcasecmp(text, "true") == 0 || strcasecmp(text, "yes") == 0) { + *out_value = true; + return true; + } + if (strcmp(text, "0") == 0 || strcasecmp(text, "false") == 0 || strcasecmp(text, "no") == 0) { + *out_value = false; + return true; + } + return false; +} + +static const char *map_density_text(const char *text) { + if (text == NULL || text[0] == '\0') { + return "中等"; + } + if (strcasecmp(text, "light") == 0 || strcmp(text, "较淡") == 0) { + return "较淡"; + } + if (strcasecmp(text, "medium") == 0 || strcmp(text, "中等") == 0) { + return "中等"; + } + if (strcasecmp(text, "dark") == 0 || strcmp(text, "较浓") == 0) { + return "较浓"; + } + if (strcasecmp(text, "max") == 0 || strcmp(text, "最深") == 0) { + return "最深"; + } + return "中等"; +} + +static void parse_image_upload_options(httpd_req_t *req, + bool *out_scale_to_width, + uint8_t *out_threshold, + bool *out_invert, + uint16_t *out_max_height, + const char **out_density, + bool *out_direct_ignore_precheck) { + if (out_scale_to_width != NULL) { + *out_scale_to_width = true; + } + if (out_threshold != NULL) { + *out_threshold = 160; + } + if (out_invert != NULL) { + *out_invert = false; + } + if (out_max_height != NULL) { + *out_max_height = 2200; + } + if (out_density != NULL) { + *out_density = "中等"; + } + if (out_direct_ignore_precheck != NULL) { + *out_direct_ignore_precheck = false; + } + + if (req == NULL) { + return; + } + + int qlen = httpd_req_get_url_query_len(req); + if (qlen <= 0 || qlen > 512) { + return; + } + + char *query = (char *)calloc(1, (size_t)qlen + 1); + if (query == NULL) { + return; + } + + if (httpd_req_get_url_query_str(req, query, (size_t)qlen + 1) != ESP_OK) { + free(query); + return; + } + + char value[48] = {0}; + if (httpd_query_key_value(query, "scale_to_width", value, sizeof(value)) == ESP_OK && + out_scale_to_width != NULL) { + bool parsed = *out_scale_to_width; + if (parse_bool_text(value, &parsed)) { + *out_scale_to_width = parsed; + } + } + + if (httpd_query_key_value(query, "invert", value, sizeof(value)) == ESP_OK && out_invert != NULL) { + bool parsed = *out_invert; + if (parse_bool_text(value, &parsed)) { + *out_invert = parsed; + } + } + + if (httpd_query_key_value(query, "threshold", value, sizeof(value)) == ESP_OK && out_threshold != NULL) { + long v = strtol(value, NULL, 10); + if (v >= 0 && v <= 255) { + *out_threshold = (uint8_t)v; + } + } + + if (httpd_query_key_value(query, "max_height", value, sizeof(value)) == ESP_OK && out_max_height != NULL) { + long v = strtol(value, NULL, 10); + if (v >= 64 && v <= 3000) { + *out_max_height = (uint16_t)v; + } + } + + if (httpd_query_key_value(query, "density", value, sizeof(value)) == ESP_OK && out_density != NULL) { + *out_density = map_density_text(value); + } + + if (httpd_query_key_value(query, "ignore_precheck", value, sizeof(value)) == ESP_OK && + out_direct_ignore_precheck != NULL) { + bool parsed = *out_direct_ignore_precheck; + if (parse_bool_text(value, &parsed)) { + *out_direct_ignore_precheck = parsed; + } + } + + free(query); +} + +static void image_print_options_set_defaults(image_print_options_t *out) { + if (out == NULL) { + return; + } + out->scale_to_width = true; + out->threshold = 160; + out->invert = false; + out->max_height = 2200; + out->density = "中等"; + out->direct_ignore_precheck = false; +} + +static void parse_image_print_options_from_json(cJSON *json, image_print_options_t *out) { + if (json == NULL || out == NULL) { + return; + } + + cJSON *jscale = cJSON_GetObjectItemCaseSensitive(json, "scale_to_width"); + cJSON *jthreshold = cJSON_GetObjectItemCaseSensitive(json, "threshold"); + cJSON *jinvert = cJSON_GetObjectItemCaseSensitive(json, "invert"); + cJSON *jmaxh = cJSON_GetObjectItemCaseSensitive(json, "max_height"); + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + out->scale_to_width = rest_server_json_bool_with_default(jscale, out->scale_to_width); + out->invert = rest_server_json_bool_with_default(jinvert, out->invert); + if (cJSON_IsNumber(jthreshold) && jthreshold->valuedouble >= 0 && jthreshold->valuedouble <= 255) { + out->threshold = (uint8_t)jthreshold->valuedouble; + } + if (cJSON_IsNumber(jmaxh) && jmaxh->valuedouble >= 64 && jmaxh->valuedouble <= 3000) { + out->max_height = (uint16_t)jmaxh->valuedouble; + } + if (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) { + out->density = map_density_text(jdensity->valuestring); + } + out->direct_ignore_precheck = rest_server_json_bool_with_default(jignore, out->direct_ignore_precheck); +} + +static bool parse_image_size_text(const char *text, uint32_t *out_w, uint32_t *out_h) { + if (text == NULL || out_w == NULL || out_h == NULL) { + return false; + } + + const char *sep = strchr(text, '*'); + if (sep == NULL || sep == text || *(sep + 1) == '\0') { + return false; + } + + char wbuf[12] = {0}; + char hbuf[12] = {0}; + size_t wlen = (size_t)(sep - text); + size_t hlen = strlen(sep + 1); + if (wlen == 0 || hlen == 0 || wlen >= sizeof(wbuf) || hlen >= sizeof(hbuf)) { + return false; + } + + memcpy(wbuf, text, wlen); + memcpy(hbuf, sep + 1, hlen); + wbuf[wlen] = '\0'; + hbuf[hlen] = '\0'; + + char *wend = NULL; + char *hend = NULL; + long w = strtol(wbuf, &wend, 10); + long h = strtol(hbuf, &hend, 10); + if (wend == wbuf || hend == hbuf || *wend != '\0' || *hend != '\0') { + return false; + } + if (w <= 0 || h <= 0) { + return false; + } + + *out_w = (uint32_t)w; + *out_h = (uint32_t)h; + return true; +} + +static bool parse_image_generation_options(cJSON *json, + image_generate_options_t *out, + char *err, + size_t err_len) { + if (json == NULL || out == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return false; + } + + memset(out, 0, sizeof(*out)); + out->timeout_ms = domain_policy_image_generation_timeout_default_ms(); + out->fetch_timeout_ms = domain_policy_image_download_timeout_default_ms(); + + cJSON *jprompt = cJSON_GetObjectItemCaseSensitive(json, "prompt"); + if (!cJSON_IsString(jprompt) || jprompt->valuestring == NULL || jprompt->valuestring[0] == '\0') { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "prompt is required"); + } + return false; + } + + size_t prompt_len = strlen(jprompt->valuestring); + if (prompt_len > 800) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "prompt too long, max 800 chars"); + } + return false; + } + strlcpy(out->prompt, jprompt->valuestring, sizeof(out->prompt)); + + cJSON *jsize = cJSON_GetObjectItemCaseSensitive(json, "size"); + if (cJSON_IsString(jsize) && jsize->valuestring != NULL && jsize->valuestring[0] != '\0') { + uint32_t w = 0; + uint32_t h = 0; + if (!parse_image_size_text(jsize->valuestring, &w, &h)) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "size must be like 1120*1440"); + } + return false; + } + + uint64_t pixels = (uint64_t)w * (uint64_t)h; + if (pixels < (512ULL * 512ULL) || pixels > (2048ULL * 2048ULL)) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "size pixels must be in [512*512, 2048*2048]"); + } + return false; + } + + out->has_size = true; + strlcpy(out->size, jsize->valuestring, sizeof(out->size)); + } + + cJSON *jextend = cJSON_GetObjectItemCaseSensitive(json, "prompt_extend"); + out->prompt_extend = rest_server_json_bool_with_default(jextend, false); + + cJSON *jseed = cJSON_GetObjectItemCaseSensitive(json, "seed"); + if (cJSON_IsNumber(jseed)) { + if (jseed->valuedouble < 0 || jseed->valuedouble > 2147483647.0) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "seed must be in [0, 2147483647]"); + } + return false; + } + out->has_seed = true; + out->seed = (uint32_t)jseed->valuedouble; + } + + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + if (cJSON_IsNumber(jtimeout)) { + if (jtimeout->valuedouble < domain_policy_image_generation_timeout_min_ms() || + jtimeout->valuedouble > domain_policy_image_generation_timeout_max_ms()) { + if (err != NULL && err_len > 0) { + snprintf(err, + err_len, + "timeout_ms must be %u..%u", + (unsigned)domain_policy_image_generation_timeout_min_ms(), + (unsigned)domain_policy_image_generation_timeout_max_ms()); + } + return false; + } + out->timeout_ms = (uint32_t)jtimeout->valuedouble; + } + + cJSON *jfetch_timeout = cJSON_GetObjectItemCaseSensitive(json, "fetch_timeout_ms"); + if (cJSON_IsNumber(jfetch_timeout)) { + if (jfetch_timeout->valuedouble < domain_policy_image_download_timeout_min_ms() || + jfetch_timeout->valuedouble > domain_policy_image_download_timeout_max_ms()) { + if (err != NULL && err_len > 0) { + snprintf(err, + err_len, + "fetch_timeout_ms must be %u..%u", + (unsigned)domain_policy_image_download_timeout_min_ms(), + (unsigned)domain_policy_image_download_timeout_max_ms()); + } + return false; + } + out->fetch_timeout_ms = (uint32_t)jfetch_timeout->valuedouble; + } + + return true; +} + +static esp_err_t rest_server_send_image_generation_error(httpd_req_t *req, + esp_err_t rc, + const char *msg) { + const char *message = (msg != NULL && msg[0] != '\0') ? msg : "image generation failed"; + if (rc == ESP_ERR_INVALID_ARG) { + return rest_server_send_error(req, "400 Bad Request", message); + } + if (rc == ESP_ERR_INVALID_STATE) { + return rest_server_send_error(req, "503 Service Unavailable", message); + } + if (rc == ESP_ERR_TIMEOUT) { + return rest_server_send_error(req, "504 Gateway Timeout", message); + } + if (rc == ESP_ERR_NO_MEM) { + return rest_server_send_error(req, "500 Internal Server Error", message); + } + return rest_server_send_error(req, "502 Bad Gateway", message); +} + +static void rest_server_try_preview_raster(const char *source, + const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height) { + if (raster == NULL || raster_len == 0 || width == 0 || height == 0) { + return; + } + + char preview_err[96] = {0}; + esp_err_t preview_rc = screen_preview_show_raster(raster, + raster_len, + width, + height, + SCREEN_PREVIEW_TIMEOUT_MS, + preview_err, + sizeof(preview_err)); + if (preview_rc == ESP_OK) { + ESP_LOGI(TAG, + "screen preview updated (%s), size=%ux%u", + source != NULL ? source : "unknown", + (unsigned)width, + (unsigned)height); + return; + } + if (preview_rc == ESP_ERR_NOT_SUPPORTED) { + return; + } + + ESP_LOGW(TAG, + "screen preview skipped (%s), rc=0x%x, msg=%s", + source != NULL ? source : "unknown", + (unsigned)preview_rc, + preview_err[0] != '\0' ? preview_err : "preview failed"); +} + +static esp_err_t rest_server_print_image_binary(httpd_req_t *req) { + bool scale_to_width = true; + uint8_t threshold = 160; + bool invert = false; + uint16_t max_height = 2200; + const char *density = "中等"; + bool direct_ignore_precheck = false; + parse_image_upload_options(req, + &scale_to_width, + &threshold, + &invert, + &max_height, + &density, + &direct_ignore_precheck); + + ESP_LOGI(TAG, + "image process start (upload), png_bytes=%u, scale_to_width=%d, threshold=%u, invert=%d, max_height=%u, density=%s, ignore_precheck=%d", + (unsigned)req->content_len, + scale_to_width, + (unsigned)threshold, + invert, + (unsigned)max_height, + density != NULL ? density : "中等", + direct_ignore_precheck); + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + uint16_t width = 0; + uint16_t height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char decode_err[128] = {0}; + esp_err_t decode_rc = raster_tools_convert_png_to_raster_384((const uint8_t *)body, + (size_t)req->content_len, + scale_to_width, + threshold, + invert, + max_height, + &width, + &height, + &raster, + &raster_len, + decode_err, + sizeof(decode_err)); + free(body); + if (decode_rc != ESP_OK) { + ESP_LOGW(TAG, + "image process failed (upload), rc=0x%x, msg=%s", + (unsigned)decode_rc, + decode_err[0] != '\0' ? decode_err : "decode png failed"); + return rest_server_send_error(req, + "400 Bad Request", + decode_err[0] != '\0' ? decode_err : "decode png failed"); + } + + ESP_LOGI(TAG, + "image process done (upload), raster_size=%ux%u, raster_bytes=%u", + (unsigned)width, + (unsigned)height, + (unsigned)raster_len); + rest_server_try_preview_raster("upload", raster, raster_len, width, height); + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + density, + direct_ignore_precheck, + NULL, + NULL); + free(raster); + return submit_rc; +} + +static esp_err_t rest_server_print_image_generate(httpd_req_t *req) { + char *body = NULL; + cJSON *json = NULL; + image_generation_result_t *gen_result = NULL; + uint8_t *raster = NULL; + char request_id[80] = {0}; + printer_status_poll_pause_token_t status_poll_pause_token = 0; + esp_err_t ret = ESP_FAIL; + + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + json = cJSON_Parse(body); + free(body); + body = NULL; + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + image_generate_options_t gen_opt = {0}; + char parse_err[128] = {0}; + if (!parse_image_generation_options(json, &gen_opt, parse_err, sizeof(parse_err))) { + ret = rest_server_send_error(req, + "400 Bad Request", + parse_err[0] != '\0' ? parse_err : "invalid image options"); + goto cleanup; + } + + image_print_options_t print_opt = {0}; + image_print_options_set_defaults(&print_opt); + parse_image_print_options_from_json(json, &print_opt); + cJSON_Delete(json); + json = NULL; + + ESP_LOGI(TAG, + "image generate start, prompt_len=%u, size=%s, prompt_extend=%d, seed=%s, timeout_ms=%u, fetch_timeout_ms=%u", + (unsigned)strlen(gen_opt.prompt), + gen_opt.has_size ? gen_opt.size : "default", + gen_opt.prompt_extend, + gen_opt.has_seed ? "set" : "auto", + (unsigned)gen_opt.timeout_ms, + (unsigned)gen_opt.fetch_timeout_ms); + ESP_LOGI(TAG, + "image process config, scale_to_width=%d, threshold=%u, invert=%d, max_height=%u, density=%s, ignore_precheck=%d", + print_opt.scale_to_width, + (unsigned)print_opt.threshold, + print_opt.invert, + (unsigned)print_opt.max_height, + print_opt.density != NULL ? print_opt.density : "中等", + print_opt.direct_ignore_precheck); + + image_generation_request_t gen_req = { + .prompt = gen_opt.prompt, + .size = gen_opt.has_size ? gen_opt.size : NULL, + .prompt_extend = gen_opt.prompt_extend, + .has_seed = gen_opt.has_seed, + .seed = gen_opt.seed, + .generation_timeout_ms = gen_opt.timeout_ms, + .download_timeout_ms = gen_opt.fetch_timeout_ms, + }; + + gen_result = (image_generation_result_t *)calloc(1, sizeof(*gen_result)); + if (gen_result == NULL) { + ret = rest_server_send_error(req, "500 Internal Server Error", "no memory"); + goto cleanup; + } + image_generation_result_reset(gen_result); + + char model_err[160] = {0}; + status_poll_pause_token = printer_protocol_status_poll_pause_acquire(); + esp_err_t gen_rc = image_generation_generate_png(&gen_req, + gen_result, + model_err, + sizeof(model_err)); + printer_protocol_status_poll_pause_release(&status_poll_pause_token); + if (gen_rc != ESP_OK) { + ESP_LOGW(TAG, + "image generate failed, rc=0x%x, msg=%s", + (unsigned)gen_rc, + model_err[0] != '\0' ? model_err : "image generation failed"); + ret = rest_server_send_image_generation_error(req, gen_rc, model_err); + goto cleanup; + } + + if (gen_result->request_id[0] != '\0') { + strlcpy(request_id, gen_result->request_id, sizeof(request_id)); + } + + ESP_LOGI(TAG, + "image generate done, request_id=%s, model_size=%ux%u, png_bytes=%u", + request_id[0] != '\0' ? request_id : "-", + (unsigned)gen_result->width, + (unsigned)gen_result->height, + (unsigned)gen_result->png_len); + + uint16_t width = 0; + uint16_t height = 0; + size_t raster_len = 0; + char decode_err[128] = {0}; + esp_err_t decode_rc = raster_tools_convert_png_to_raster_384(gen_result->png, + gen_result->png_len, + print_opt.scale_to_width, + print_opt.threshold, + print_opt.invert, + print_opt.max_height, + &width, + &height, + &raster, + &raster_len, + decode_err, + sizeof(decode_err)); + if (decode_rc != ESP_OK) { + ESP_LOGW(TAG, + "image process failed (generated), rc=0x%x, msg=%s", + (unsigned)decode_rc, + decode_err[0] != '\0' ? decode_err : "decode generated image failed"); + ret = rest_server_send_error(req, + "400 Bad Request", + decode_err[0] != '\0' ? decode_err : "decode generated image failed"); + goto cleanup; + } + + ESP_LOGI(TAG, + "image process done (generated), raster_size=%ux%u, raster_bytes=%u", + (unsigned)width, + (unsigned)height, + (unsigned)raster_len); + rest_server_try_preview_raster("generated", raster, raster_len, width, height); + + char warning[160] = {0}; + if (request_id[0] != '\0') { + snprintf(warning, sizeof(warning), "z-image request_id=%s", request_id); + } + + ret = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + print_opt.density, + print_opt.direct_ignore_precheck, + warning, + request_id); + +cleanup: + printer_protocol_status_poll_pause_release(&status_poll_pause_token); + if (body != NULL) { + free(body); + } + if (json != NULL) { + cJSON_Delete(json); + } + if (raster != NULL) { + free(raster); + } + if (gen_result != NULL) { + image_generation_result_free(gen_result); + free(gen_result); + } + printer_runtime_status_t runtime = {0}; + printer_protocol_get_runtime_status(&runtime); + if (!runtime.busy) { + image_generation_schedule_prewarm(); + } + return ret; +} + +esp_err_t rest_server_print_image_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char content_type[96] = {0}; + if (httpd_req_get_hdr_value_str(req, "Content-Type", content_type, sizeof(content_type)) == ESP_OK) { + if (strstr(content_type, "application/json") != NULL) { + return rest_server_print_image_generate(req); + } + if (strstr(content_type, "image/png") == NULL) { + return rest_server_send_error(req, + "415 Unsupported Media Type", + "Content-Type must be application/json or image/png"); + } + } + + return rest_server_print_image_binary(req); +} diff --git a/components/control_plane/src/rest_server_print_render.c b/components/control_plane/src/rest_server_print_render.c new file mode 100644 index 0000000..cab1d82 --- /dev/null +++ b/components/control_plane/src/rest_server_print_render.c @@ -0,0 +1,540 @@ +#include "rest_server_internal.h" + +#include +#include +#include +#include + +#include "domain.h" + +static esp_err_t decode_image_json_to_raster(cJSON *json, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len) { + if (json == NULL || out_width == NULL || out_height == NULL || out_raster == NULL || out_len == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + *out_width = 0; + *out_height = 0; + *out_raster = NULL; + *out_len = 0; + + cJSON *jwidth = cJSON_GetObjectItemCaseSensitive(json, "width"); + cJSON *jheight = cJSON_GetObjectItemCaseSensitive(json, "height"); + cJSON *jencoding = cJSON_GetObjectItemCaseSensitive(json, "encoding"); + cJSON *jdata = cJSON_GetObjectItemCaseSensitive(json, "data"); + + if (!cJSON_IsNumber(jwidth) || !cJSON_IsNumber(jheight) || + !cJSON_IsString(jencoding) || !cJSON_IsString(jdata)) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "missing required image fields"); + } + return ESP_ERR_INVALID_ARG; + } + + uint16_t width = (uint16_t)jwidth->valuedouble; + uint16_t height = (uint16_t)jheight->valuedouble; + if (width == 0 || height == 0) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid image size"); + } + return ESP_ERR_INVALID_ARG; + } + + if (strcmp(jencoding->valuestring, "base64_msb_1bpp") == 0) { + uint8_t *raw = NULL; + size_t raw_len = 0; + esp_err_t b64_rc = rest_server_base64_decode_alloc(jdata->valuestring, &raw, &raw_len); + if (b64_rc != ESP_OK) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid base64"); + } + return ESP_ERR_INVALID_ARG; + } + *out_width = width; + *out_height = height; + *out_raster = raw; + *out_len = raw_len; + return ESP_OK; + } + + if (strcmp(jencoding->valuestring, "base64_gray8") == 0) { + uint8_t *gray = NULL; + size_t gray_len = 0; + esp_err_t b64_rc = rest_server_base64_decode_alloc(jdata->valuestring, &gray, &gray_len); + if (b64_rc != ESP_OK) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid base64"); + } + return ESP_ERR_INVALID_ARG; + } + + size_t expected = (size_t)width * height; + if (gray_len != expected) { + free(gray); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "gray8 size mismatch"); + } + return ESP_ERR_INVALID_SIZE; + } + + cJSON *jscale = cJSON_GetObjectItemCaseSensitive(json, "scale_to_width"); + cJSON *jthreshold = cJSON_GetObjectItemCaseSensitive(json, "threshold"); + cJSON *jinvert = cJSON_GetObjectItemCaseSensitive(json, "invert"); + cJSON *jmaxh = cJSON_GetObjectItemCaseSensitive(json, "max_height"); + + bool scale_to_width = rest_server_json_bool_with_default(jscale, true); + bool invert = rest_server_json_bool_with_default(jinvert, false); + uint8_t threshold = 160; + uint16_t max_height = 2200; + if (cJSON_IsNumber(jthreshold) && jthreshold->valuedouble >= 0 && jthreshold->valuedouble <= 255) { + threshold = (uint8_t)jthreshold->valuedouble; + } + if (cJSON_IsNumber(jmaxh) && jmaxh->valuedouble >= 64 && jmaxh->valuedouble <= 3000) { + max_height = (uint16_t)jmaxh->valuedouble; + } + + uint16_t out_w = 0; + uint16_t out_h = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + esp_err_t conv_rc = raster_tools_convert_gray8_to_raster_384(gray, + width, + height, + scale_to_width, + threshold, + invert, + max_height, + &out_w, + &out_h, + &raster, + &raster_len, + err, + err_len); + free(gray); + if (conv_rc != ESP_OK) { + return conv_rc; + } + + *out_width = out_w; + *out_height = out_h; + *out_raster = raster; + *out_len = raster_len; + return ESP_OK; + } + + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "unsupported encoding"); + } + return ESP_ERR_NOT_SUPPORTED; +} + +esp_err_t rest_server_print_qr_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jtext = cJSON_GetObjectItemCaseSensitive(json, "text"); + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jecc = cJSON_GetObjectItemCaseSensitive(json, "ecc"); + cJSON *jscale = cJSON_GetObjectItemCaseSensitive(json, "module_scale"); + cJSON *jmargin = cJSON_GetObjectItemCaseSensitive(json, "margin_modules"); + cJSON *jmaxh = cJSON_GetObjectItemCaseSensitive(json, "max_height"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + if (!cJSON_IsString(jtext) || jtext->valuestring == NULL || jtext->valuestring[0] == '\0') { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "text is required"); + } + + const char *density = (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) + ? jdensity->valuestring + : "中等"; + bool direct_ignore_precheck = rest_server_json_bool_with_default(jignore, false); + + uint8_t ecc_level = 3; /* default H */ + if (cJSON_IsString(jecc) && jecc->valuestring != NULL) { + if (strcasecmp(jecc->valuestring, "L") == 0) { + ecc_level = 0; + } else if (strcasecmp(jecc->valuestring, "M") == 0) { + ecc_level = 1; + } else if (strcasecmp(jecc->valuestring, "Q") == 0) { + ecc_level = 2; + } else if (strcasecmp(jecc->valuestring, "H") == 0) { + ecc_level = 3; + } + } + + uint8_t module_scale = 0; + uint8_t margin_modules = 2; + uint16_t max_height = 2200; + if (cJSON_IsNumber(jscale) && jscale->valuedouble >= 0 && jscale->valuedouble <= 16) { + module_scale = (uint8_t)jscale->valuedouble; + } + if (cJSON_IsNumber(jmargin) && jmargin->valuedouble >= 1 && jmargin->valuedouble <= 12) { + margin_modules = (uint8_t)jmargin->valuedouble; + } + if (cJSON_IsNumber(jmaxh) && jmaxh->valuedouble >= 64 && jmaxh->valuedouble <= 3000) { + max_height = (uint16_t)jmaxh->valuedouble; + } + + uint16_t width = 0; + uint16_t height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char render_msg[128] = {0}; + esp_err_t qr_rc = raster_tools_render_qr_384(jtext->valuestring, + module_scale, + margin_modules, + ecc_level, + max_height, + &width, + &height, + &raster, + &raster_len, + render_msg, + sizeof(render_msg)); + cJSON_Delete(json); + if (qr_rc != ESP_OK) { + return rest_server_send_error(req, + "400 Bad Request", + render_msg[0] != '\0' ? render_msg : "qr render failed"); + } + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + density, + direct_ignore_precheck, + NULL, + NULL); + free(raster); + return submit_rc; +} + +esp_err_t rest_server_print_label_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jgap = cJSON_GetObjectItemCaseSensitive(json, "gap_move_before"); + cJSON *joffset = cJSON_GetObjectItemCaseSensitive(json, "offset_tenths_mm"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + bool gap_move_before = rest_server_json_bool_with_default(jgap, true); + bool has_offset = cJSON_IsNumber(joffset); + uint8_t offset_value = 0; + if (has_offset) { + if (joffset->valuedouble < 0 || joffset->valuedouble > 254) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "offset_tenths_mm must be 0..254"); + } + offset_value = (uint8_t)joffset->valuedouble; + } + + const char *density = (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) + ? jdensity->valuestring + : "中等"; + bool direct_ignore_precheck = rest_server_json_bool_with_default(jignore, false); + + uint16_t width = 0; + uint16_t height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char decode_err[128] = {0}; + esp_err_t decode_rc = decode_image_json_to_raster(json, + &width, + &height, + &raster, + &raster_len, + decode_err, + sizeof(decode_err)); + cJSON_Delete(json); + if (decode_rc != ESP_OK) { + return rest_server_send_error(req, + "400 Bad Request", + decode_err[0] != '\0' ? decode_err : "decode image failed"); + } + + if (has_offset) { + char cmd_err[128] = {0}; + esp_err_t offset_rc = printer_protocol_set_label_offset(offset_value, + domain_policy_rest_label_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (offset_rc != ESP_OK) { + free(raster); + return rest_server_send_error(req, + "409 Conflict", + cmd_err[0] != '\0' ? cmd_err : "set label offset failed"); + } + } + + if (gap_move_before) { + char cmd_err[128] = {0}; + esp_err_t gap_rc = printer_protocol_gap_move(domain_policy_rest_label_timeout_ms(), + cmd_err, + sizeof(cmd_err)); + if (gap_rc != ESP_OK) { + free(raster); + return rest_server_send_error(req, + "409 Conflict", + cmd_err[0] != '\0' ? cmd_err : "gap move failed"); + } + } + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + density, + direct_ignore_precheck, + NULL, + NULL); + free(raster); + return submit_rc; +} + +esp_err_t rest_server_print_text_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jtext = cJSON_GetObjectItemCaseSensitive(json, "text"); + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jscale = cJSON_GetObjectItemCaseSensitive(json, "scale"); + cJSON *jline = cJSON_GetObjectItemCaseSensitive(json, "line_spacing"); + cJSON *jmaxh = cJSON_GetObjectItemCaseSensitive(json, "max_height"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + if (!cJSON_IsString(jtext) || jtext->valuestring == NULL) { + cJSON_Delete(json); + return rest_server_send_error(req, "400 Bad Request", "text is required"); + } + + const char *density = (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) + ? jdensity->valuestring + : "中等"; + bool direct_ignore_precheck = rest_server_json_bool_with_default(jignore, false); + uint8_t scale = 2; + uint8_t line_spacing = 2; + uint16_t max_height = 2000; + + if (cJSON_IsNumber(jscale) && jscale->valuedouble >= 1 && jscale->valuedouble <= 6) { + scale = (uint8_t)jscale->valuedouble; + } + if (cJSON_IsNumber(jline) && jline->valuedouble >= 0 && jline->valuedouble <= 12) { + line_spacing = (uint8_t)jline->valuedouble; + } + if (cJSON_IsNumber(jmaxh) && jmaxh->valuedouble >= 64 && jmaxh->valuedouble <= 3000) { + max_height = (uint16_t)jmaxh->valuedouble; + } + + uint16_t width = 0; + uint16_t height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char render_msg[128] = {0}; + + esp_err_t render_rc = raster_tools_render_text_384(jtext->valuestring, + scale, + line_spacing, + max_height, + &width, + &height, + &raster, + &raster_len, + render_msg, + sizeof(render_msg)); + cJSON_Delete(json); + + if (render_rc != ESP_OK) { + return rest_server_send_error(req, + "400 Bad Request", + render_msg[0] != '\0' ? render_msg : "text render failed"); + } + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + density, + direct_ignore_precheck, + render_msg, + NULL); + free(raster); + return submit_rc; +} + +esp_err_t rest_server_print_receipt_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return rest_server_send_error(req, "400 Bad Request", "invalid json"); + } + + cJSON *jtitle = cJSON_GetObjectItemCaseSensitive(json, "title"); + cJSON *jitems = cJSON_GetObjectItemCaseSensitive(json, "items"); + cJSON *jfooter = cJSON_GetObjectItemCaseSensitive(json, "footer"); + cJSON *jdensity = cJSON_GetObjectItemCaseSensitive(json, "density"); + cJSON *jscale = cJSON_GetObjectItemCaseSensitive(json, "scale"); + cJSON *jignore = cJSON_GetObjectItemCaseSensitive(json, "ignore_precheck"); + + const char *title = (cJSON_IsString(jtitle) && jtitle->valuestring != NULL) + ? jtitle->valuestring + : "TQ RECEIPT"; + const char *footer = (cJSON_IsString(jfooter) && jfooter->valuestring != NULL) + ? jfooter->valuestring + : "Thank you"; + const char *density = (cJSON_IsString(jdensity) && jdensity->valuestring != NULL) + ? jdensity->valuestring + : "中等"; + bool direct_ignore_precheck = rest_server_json_bool_with_default(jignore, false); + uint8_t scale = 2; + if (cJSON_IsNumber(jscale) && jscale->valuedouble >= 1 && jscale->valuedouble <= 4) { + scale = (uint8_t)jscale->valuedouble; + } + + size_t text_cap = 8192; + char *text = (char *)calloc(1, text_cap); + if (text == NULL) { + cJSON_Delete(json); + return rest_server_send_error(req, "500 Internal Server Error", "no memory"); + } + + size_t off = 0; + rest_server_appendf(text, text_cap, &off, "%s\n", title); + rest_server_appendf(text, text_cap, &off, "--------------------------------\n"); + + double total = 0.0; + if (cJSON_IsArray(jitems)) { + int n = cJSON_GetArraySize(jitems); + for (int i = 0; i < n; ++i) { + cJSON *it = cJSON_GetArrayItem(jitems, i); + if (!cJSON_IsObject(it)) { + continue; + } + + cJSON *jname = cJSON_GetObjectItemCaseSensitive(it, "name"); + cJSON *jqty = cJSON_GetObjectItemCaseSensitive(it, "qty"); + cJSON *jprice = cJSON_GetObjectItemCaseSensitive(it, "price"); + + const char *name = (cJSON_IsString(jname) && jname->valuestring != NULL) + ? jname->valuestring + : "item"; + int qty = cJSON_IsNumber(jqty) ? (int)jqty->valuedouble : 1; + double price = cJSON_IsNumber(jprice) ? jprice->valuedouble : 0.0; + double line_total = qty * price; + total += line_total; + + rest_server_appendf(text, + text_cap, + &off, + "%-16.16s x%-3d %8.2f\n", + name, + qty, + line_total); + } + } else { + rest_server_appendf(text, text_cap, &off, "(no items)\n"); + } + + rest_server_appendf(text, text_cap, &off, "--------------------------------\n"); + rest_server_appendf(text, text_cap, &off, "TOTAL: %.2f\n", total); + rest_server_appendf(text, text_cap, &off, "%s\n", footer); + + uint16_t width = 0; + uint16_t height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char render_msg[128] = {0}; + + esp_err_t render_rc = raster_tools_render_text_384(text, + scale, + 2, + 2200, + &width, + &height, + &raster, + &raster_len, + render_msg, + sizeof(render_msg)); + free(text); + cJSON_Delete(json); + + if (render_rc != ESP_OK) { + return rest_server_send_error(req, + "400 Bad Request", + render_msg[0] != '\0' ? render_msg : "receipt render failed"); + } + + esp_err_t submit_rc = rest_server_print_submit_raster_job_and_reply(req, + raster, + raster_len, + width, + height, + density, + direct_ignore_precheck, + render_msg, + NULL); + free(raster); + return submit_rc; +} diff --git a/components/control_plane/src/rest_server_voice.c b/components/control_plane/src/rest_server_voice.c new file mode 100644 index 0000000..5e62b73 --- /dev/null +++ b/components/control_plane/src/rest_server_voice.c @@ -0,0 +1,213 @@ +#include "rest_server_internal.h" + +#include + +#include "domain.h" + +#define VOICE_CONTROL_TIMEOUT_MIN_MS 500 +#define VOICE_CONTROL_TIMEOUT_MAX_MS 30000 + +static esp_err_t rest_server_parse_voice_timeout(httpd_req_t *req, uint32_t *out_timeout_ms) { + if (out_timeout_ms == NULL) { + return ESP_ERR_INVALID_ARG; + } + *out_timeout_ms = 0; + if (req->content_len <= 0) { + return ESP_OK; + } + + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return body_err; + } + + cJSON *json = cJSON_Parse(body); + free(body); + if (json == NULL) { + return ESP_ERR_INVALID_ARG; + } + + cJSON *jtimeout = cJSON_GetObjectItemCaseSensitive(json, "timeout_ms"); + if (jtimeout != NULL) { + if (!cJSON_IsNumber(jtimeout) || + jtimeout->valuedouble < VOICE_CONTROL_TIMEOUT_MIN_MS || + jtimeout->valuedouble > VOICE_CONTROL_TIMEOUT_MAX_MS) { + cJSON_Delete(json); + return ESP_ERR_INVALID_ARG; + } + *out_timeout_ms = (uint32_t)jtimeout->valuedouble; + } + + cJSON_Delete(json); + return ESP_OK; +} + +static void rest_server_add_voice_status(cJSON *root) { + voice_interaction_status_t st = {0}; + voice_interaction_get_status(&st); + printer_runtime_status_t printer = {0}; + printer_protocol_get_runtime_status(&printer); + + cJSON_AddBoolToObject(root, "voice_ready", st.ready); + cJSON_AddBoolToObject(root, "voice_session_active", st.session_active); + cJSON_AddBoolToObject(root, "voice_ws_connected", st.ws_connected); + cJSON_AddBoolToObject(root, "voice_started", st.started); + cJSON_AddBoolToObject(root, "voice_tap_active", st.tap_active); + cJSON_AddBoolToObject(root, "voice_marker_image_gen_running", st.marker_image_gen_running); + cJSON_AddStringToObject(root, + "voice_dialog_state", + voice_interaction_dialog_state_str(st.dialog_state)); + cJSON_AddStringToObject(root, "voice_task_id", st.task_id); + cJSON_AddStringToObject(root, "voice_dialog_id", st.dialog_id); + cJSON_AddStringToObject(root, "voice_last_error", st.last_error); + cJSON_AddNumberToObject(root, "voice_last_event_ms", (double)st.last_event_ms); + cJSON_AddNumberToObject(root, "voice_upstream_packets", (double)st.upstream_packets); + cJSON_AddNumberToObject(root, "voice_downstream_packets", (double)st.downstream_packets); + cJSON_AddBoolToObject(root, "printer_busy", printer.busy); + cJSON_AddNumberToObject(root, "queue_depth", (double)printer.queue_depth); +} + +esp_err_t rest_server_voice_status_get(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + rest_server_add_voice_status(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_voice_session_start_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint32_t timeout_ms = 0; + if (rest_server_parse_voice_timeout(req, &timeout_ms) != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + char start_err[128] = {0}; + esp_err_t rc = voice_interaction_start_with_timeout(timeout_ms, start_err, sizeof(start_err)); + if (rc != ESP_OK) { + if (rc == ESP_ERR_TIMEOUT) { + return rest_server_send_error(req, + "504 Gateway Timeout", + start_err[0] != '\0' ? start_err : "voice session start timeout"); + } + return rest_server_send_error(req, + "409 Conflict", + start_err[0] != '\0' ? start_err : "voice session start failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "voice session started"); + rest_server_add_voice_status(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_voice_session_stop_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + uint32_t timeout_ms = 0; + if (rest_server_parse_voice_timeout(req, &timeout_ms) != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + + char stop_err[128] = {0}; + esp_err_t rc = voice_interaction_stop_with_timeout(timeout_ms, stop_err, sizeof(stop_err)); + if (rc != ESP_OK) { + if (rc == ESP_ERR_TIMEOUT) { + return rest_server_send_error(req, + "504 Gateway Timeout", + stop_err[0] != '\0' ? stop_err : "voice session stop timeout"); + } + return rest_server_send_error(req, + "409 Conflict", + stop_err[0] != '\0' ? stop_err : "voice session stop failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "voice session stopped"); + rest_server_add_voice_status(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_voice_tap_start_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + if (req->content_len > 0) { + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + free(body); + } + + char tap_err[128] = {0}; + esp_err_t rc = voice_interaction_tap_start(tap_err, sizeof(tap_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, + "409 Conflict", + tap_err[0] != '\0' ? tap_err : "tap start failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "tap started"); + rest_server_add_voice_status(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} + +esp_err_t rest_server_voice_tap_cancel_post(httpd_req_t *req) { + if (!rest_server_auth_ok(req)) { + return rest_server_send_error(req, "401 Unauthorized", "unauthorized"); + } + + if (req->content_len > 0) { + char *body = NULL; + esp_err_t body_err = rest_server_read_body(req, &body); + if (body_err != ESP_OK) { + return rest_server_send_error(req, "400 Bad Request", "invalid request body"); + } + free(body); + } + + char tap_err[128] = {0}; + esp_err_t rc = voice_interaction_tap_cancel(tap_err, sizeof(tap_err)); + if (rc != ESP_OK) { + return rest_server_send_error(req, + "409 Conflict", + tap_err[0] != '\0' ? tap_err : "tap cancel failed"); + } + + cJSON *root = cJSON_CreateObject(); + cJSON_AddBoolToObject(root, "ok", true); + cJSON_AddStringToObject(root, "message", "tap canceled"); + rest_server_add_voice_status(root); + + esp_err_t err = rest_server_send_json(req, "200 OK", root); + cJSON_Delete(root); + return err; +} diff --git a/components/domain/CMakeLists.txt b/components/domain/CMakeLists.txt new file mode 100644 index 0000000..e2eafac --- /dev/null +++ b/components/domain/CMakeLists.txt @@ -0,0 +1,37 @@ +idf_component_register( + SRCS + "src/printer_protocol.c" + "src/printer_protocol_jobs.c" + "src/printer_protocol_worker.c" + "src/printer_protocol_commands.c" + "src/raster_tools.c" + "src/raster_tools_image_qr.c" + "src/image_generation.c" + "src/screen_preview.c" + "src/system_runtime.c" + "src/domain_runtime_contracts.c" + "src/voice_interaction.c" + "src/voice_interaction_common.c" + "src/voice_interaction_ws.c" + "src/voice_interaction_ws_protocol.c" + "src/voice_interaction_ws_audio.c" + "src/voice_interaction_marker.c" + "src/voice_interaction_tasks.c" + "third_party/qrcodegen.c" + INCLUDE_DIRS + "include" + PRIV_INCLUDE_DIRS + "internal" + "third_party" + REQUIRES + platform + esp_http_client + esp_websocket_client + espressif__libpng + json + mbedtls + esp_coex + EMBED_FILES + "assets/fonts/cn16_index.bin" + "assets/fonts/cn16_glyphs.bin" +) diff --git a/components/domain/README.md b/components/domain/README.md new file mode 100644 index 0000000..e16ed16 --- /dev/null +++ b/components/domain/README.md @@ -0,0 +1,9 @@ +# Domain Layer + +Purpose: business capabilities with single responsibility per domain service. + +Rules: +- Expose stable domain APIs in `include/`. +- Keep implementation details in `internal/` and `src/`. +- No direct cross-domain internal state access. +- Cross-domain interactions must use events or Port interfaces. diff --git a/components/domain/assets/fonts/cn16_glyphs.bin b/components/domain/assets/fonts/cn16_glyphs.bin new file mode 100644 index 0000000000000000000000000000000000000000..631b943a6dd15ad4c42df31508848a1c3c66c39f GIT binary patch literal 238240 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
};)N3ipHaD54k|}ex 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
  • ^(lVTs^?ZC|Hi{# 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 J#r>Re{XdX;z&ii{ literal 0 HcmV?d00001 diff --git a/components/domain/assets/fonts/cn16_index.bin b/components/domain/assets/fonts/cn16_index.bin new file mode 100644 index 0000000000000000000000000000000000000000..2638f0d345e2dc73b0f864e3481775da282dbd2f GIT binary patch literal 44670 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 +#include +#include + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// ---------- system_runtime ---------- +esp_err_t system_runtime_start(void); +esp_err_t system_runtime_shutdown(void); +esp_err_t system_runtime_bootstrap(void); + +bool system_runtime_wifi_ready(void); +void system_runtime_get_ip(char *buf, size_t buf_len); + +// ---------- domain_policy ---------- +uint32_t domain_policy_lifecycle_start_retry_count(void); +uint32_t domain_policy_lifecycle_retry_backoff_ms(uint32_t attempt); +bool domain_policy_is_retryable_error(esp_err_t err); + +uint32_t domain_policy_printer_stop_timeout_ms(void); + +uint32_t domain_policy_rest_printer_connect_timeout_ms(void); +uint32_t domain_policy_rest_printer_connect_timeout_min_ms(void); +uint32_t domain_policy_rest_printer_connect_timeout_max_ms(void); + +uint32_t domain_policy_rest_label_timeout_ms(void); +uint32_t domain_policy_rest_label_timeout_min_ms(void); +uint32_t domain_policy_rest_label_timeout_max_ms(void); + +uint32_t domain_policy_rest_ota_timeout_ms(void); +uint32_t domain_policy_rest_ota_timeout_min_ms(void); +uint32_t domain_policy_rest_ota_timeout_max_ms(void); + +uint32_t domain_policy_image_generation_timeout_default_ms(void); +uint32_t domain_policy_image_generation_timeout_min_ms(void); +uint32_t domain_policy_image_generation_timeout_max_ms(void); + +uint32_t domain_policy_image_download_timeout_default_ms(void); +uint32_t domain_policy_image_download_timeout_min_ms(void); +uint32_t domain_policy_image_download_timeout_max_ms(void); + +// ---------- domain_diagnostics ---------- +typedef enum { + DOMAIN_DIAG_COUNTER_LIFECYCLE_START_ATTEMPT = 0, + DOMAIN_DIAG_COUNTER_LIFECYCLE_START_SUCCESS, + DOMAIN_DIAG_COUNTER_LIFECYCLE_START_FAILED, + DOMAIN_DIAG_COUNTER_LIFECYCLE_START_RETRY, + DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_ATTEMPT, + DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_SUCCESS, + DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_FAILED, + DOMAIN_DIAG_COUNTER_WIFI_CONNECT_SUCCESS, + DOMAIN_DIAG_COUNTER_WIFI_CONNECT_FAILED, + DOMAIN_DIAG_COUNTER_WIFI_CONNECT_TIMEOUT, + DOMAIN_DIAG_COUNTER_PRINTER_JOB_SUBMITTED, + DOMAIN_DIAG_COUNTER_PRINTER_JOB_SUCCESS, + DOMAIN_DIAG_COUNTER_PRINTER_JOB_FAILED, + DOMAIN_DIAG_COUNTER_PRINTER_JOB_CANCELED, + DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_ATTEMPT, + DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_SUCCESS, + DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_FAILED, + DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT, + DOMAIN_DIAG_COUNTER_REST_RESPONSES_TOTAL, + DOMAIN_DIAG_COUNTER_REST_ERRORS_TOTAL, + DOMAIN_DIAG_COUNTER_MAX, +} domain_diag_counter_t; + +typedef enum { + DOMAIN_DIAG_GAUGE_LIFECYCLE_STATE = 0, + DOMAIN_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, + DOMAIN_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, + DOMAIN_DIAG_GAUGE_MAX, +} domain_diag_gauge_t; + +typedef struct { + uint64_t counters[DOMAIN_DIAG_COUNTER_MAX]; + int32_t gauges[DOMAIN_DIAG_GAUGE_MAX]; + int64_t last_error_ms; + esp_err_t last_error_code; + char last_error_source[32]; + char last_error_message[96]; +} domain_diag_snapshot_t; + +void domain_diag_counter_add(domain_diag_counter_t counter, uint32_t delta); +void domain_diag_set_gauge(domain_diag_gauge_t gauge, int32_t value); +void domain_diag_record_error(const char *source, esp_err_t code, const char *message); +void domain_diag_get_snapshot(domain_diag_snapshot_t *out_snapshot); +const char *domain_diag_counter_name(domain_diag_counter_t counter); +const char *domain_diag_gauge_name(domain_diag_gauge_t gauge); + +// ---------- raster_tools ---------- +esp_err_t raster_tools_render_text_384(const char *text, + uint8_t scale, + uint8_t line_spacing, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len); + +esp_err_t raster_tools_convert_gray8_to_raster_384(const uint8_t *gray, + uint16_t src_width, + uint16_t src_height, + bool scale_to_width, + uint8_t threshold, + bool invert, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len); + +esp_err_t raster_tools_convert_png_to_raster_384(const uint8_t *png, + size_t png_len, + bool scale_to_width, + uint8_t threshold, + bool invert, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len); + +esp_err_t raster_tools_render_qr_384(const char *text, + uint8_t module_scale, + uint8_t margin_modules, + uint8_t ecc_level, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len); + +// ---------- image_generation ---------- +typedef struct { + const char *prompt; + const char *size; + bool prompt_extend; + bool has_seed; + uint32_t seed; + uint32_t generation_timeout_ms; + uint32_t download_timeout_ms; +} image_generation_request_t; + +typedef struct { + uint8_t *png; + size_t png_len; + char image_url[1024]; + char output_prompt[256]; + char request_id[80]; + uint16_t width; + uint16_t height; +} image_generation_result_t; + +void image_generation_result_reset(image_generation_result_t *result); +void image_generation_result_free(image_generation_result_t *result); +void image_generation_schedule_prewarm(void); + +esp_err_t image_generation_generate_png(const image_generation_request_t *req, + image_generation_result_t *out_result, + char *err, + size_t err_len); + +// ---------- screen_preview ---------- +esp_err_t screen_preview_show_raster(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len); +esp_err_t screen_preview_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len); + +// ---------- printer_protocol ---------- +typedef enum { + PRINT_JOB_STATE_NONE = 0, + PRINT_JOB_STATE_QUEUED, + PRINT_JOB_STATE_RUNNING, + PRINT_JOB_STATE_SUCCESS, + PRINT_JOB_STATE_FAILED, + PRINT_JOB_STATE_CANCELED, +} print_job_state_t; + +typedef struct { + uint32_t id; + print_job_state_t state; + uint8_t progress; + uint16_t width; + uint16_t height; + size_t data_len; + char density[16]; + char error[96]; + int64_t created_ms; + int64_t started_ms; + int64_t finished_ms; +} print_job_info_t; + +typedef struct { + uint8_t major; + uint8_t minor; + uint8_t patch; +} printer_ota_version_t; + +typedef enum { + PRINTER_BACKEND_BLE = 0, + PRINTER_BACKEND_DIRECT = 1, +} printer_backend_t; + +typedef struct { + printer_backend_t backend; + const char *name; + uint32_t timeout_ms; +} printer_connect_options_t; + +typedef struct { + // Direct backend only: bypass paper/temp/battery precheck for this print job. + bool direct_ignore_precheck; +} printer_print_options_t; + +typedef struct { + uint16_t shift_clock_high_us; + uint16_t shift_clock_low_us; + uint16_t latch_pulse_us; + bool strobe_active_high; + bool boost_active_high; + uint16_t override_strobe_on_us; + uint16_t override_strobe_interval_us; + uint16_t override_motor_step_us; + uint8_t override_steps_per_line; +} printer_direct_debug_config_t; + +typedef struct { + bool supports_connect; + bool supports_gap_move; + bool supports_label_offset; + bool supports_ota; +} printer_capabilities_t; + +typedef struct { + printer_backend_t backend; + bool connected; + bool transport_ready; + bool notify_ready; + bool busy; + bool has_paper; + int8_t paper_gpio_level; + uint8_t paper_present_level; + uint8_t battery_percent; + float temperature; + uint16_t mtu; + bool supports_gap_move; + bool supports_label_offset; + bool supports_ota; + uint32_t queue_depth; + int64_t last_status_ms; +} printer_runtime_status_t; + +typedef uint32_t printer_status_poll_pause_token_t; + +esp_err_t printer_protocol_init(void); +esp_err_t printer_protocol_stop(uint32_t timeout_ms); + +esp_err_t printer_protocol_set_backend(printer_backend_t backend, char *err, size_t err_len); +printer_backend_t printer_protocol_get_backend(void); + +esp_err_t printer_protocol_connect(const char *target_name, uint32_t timeout_ms); +esp_err_t printer_protocol_connect_ex(const printer_connect_options_t *opt, char *err, size_t err_len); +void printer_protocol_disconnect(void); +void printer_protocol_get_capabilities(printer_capabilities_t *out_capabilities); +esp_err_t printer_protocol_get_direct_debug_config(printer_direct_debug_config_t *out_config, + char *err, + size_t err_len); +esp_err_t printer_protocol_set_direct_debug_config(const printer_direct_debug_config_t *config, + bool reset_defaults, + char *err, + size_t err_len); + +void printer_protocol_get_runtime_status(printer_runtime_status_t *out_status); +printer_status_poll_pause_token_t printer_protocol_status_poll_pause_acquire(void); +void printer_protocol_status_poll_pause_release(printer_status_poll_pause_token_t *token); + +esp_err_t printer_protocol_submit_raster_job(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + const char *density, + uint32_t *out_job_id, + char *err, + size_t err_len); +esp_err_t printer_protocol_submit_raster_job_ex(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + const char *density, + const printer_print_options_t *options, + uint32_t *out_job_id, + char *err, + size_t err_len); + +bool printer_protocol_get_job(uint32_t job_id, print_job_info_t *out_info); +esp_err_t printer_protocol_list_jobs(print_job_info_t *out_jobs, size_t max_jobs, size_t *out_count); +esp_err_t printer_protocol_cancel_job(uint32_t job_id, char *err, size_t err_len); +size_t printer_protocol_cleanup_jobs(bool include_success, bool include_failed, bool include_canceled); + +esp_err_t printer_protocol_gap_move(uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t printer_protocol_get_label_offset(uint8_t *out_offset, uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t printer_protocol_set_label_offset(uint8_t offset, uint32_t timeout_ms, char *err, size_t err_len); + +esp_err_t printer_protocol_ota_jump_boot(uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t printer_protocol_ota_jump_app(uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t printer_protocol_ota_erase_page(uint16_t page_num, uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t printer_protocol_ota_write_frame(uint16_t packet_num, + bool is_last_frame, + const uint8_t *data, + size_t data_len, + uint32_t timeout_ms, + char *err, + size_t err_len); +esp_err_t printer_protocol_ota_get_version(printer_ota_version_t *out_version, + uint32_t timeout_ms, + char *err, + size_t err_len); + +const char *printer_protocol_job_state_str(print_job_state_t state); + +// ---------- voice_interaction ---------- +typedef enum { + VOICE_DIALOG_STATE_IDLE = 0, + VOICE_DIALOG_STATE_LISTENING, + VOICE_DIALOG_STATE_THINKING, + VOICE_DIALOG_STATE_RESPONDING, +} voice_dialog_state_t; + +typedef struct { + bool ready; + bool session_active; + bool ws_connected; + bool started; + bool tap_active; + bool marker_image_gen_running; + voice_dialog_state_t dialog_state; + char task_id[40]; + char dialog_id[40]; + char last_error[128]; + int64_t last_event_ms; + uint32_t upstream_packets; + uint32_t downstream_packets; +} voice_interaction_status_t; + +esp_err_t voice_interaction_init(void); +esp_err_t voice_interaction_start_with_timeout(uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t voice_interaction_start(char *err, size_t err_len); +esp_err_t voice_interaction_stop_with_timeout(uint32_t timeout_ms, char *err, size_t err_len); +esp_err_t voice_interaction_stop(char *err, size_t err_len); + +esp_err_t voice_interaction_tap_start(char *err, size_t err_len); +esp_err_t voice_interaction_tap_cancel(char *err, size_t err_len); + +void voice_interaction_get_status(voice_interaction_status_t *out_status); +const char *voice_interaction_dialog_state_str(voice_dialog_state_t state); + +#ifdef __cplusplus +} +#endif diff --git a/components/domain/internal/.gitkeep b/components/domain/internal/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/domain/internal/printer_protocol_internal.h b/components/domain/internal/printer_protocol_internal.h new file mode 100644 index 0000000..211d765 --- /dev/null +++ b/components/domain/internal/printer_protocol_internal.h @@ -0,0 +1,124 @@ +#pragma once + +#include +#include +#include + +#include "domain.h" +#include "esp_err.h" +#include "platform.h" +#include "freertos/FreeRTOS.h" +#include "freertos/event_groups.h" +#include "freertos/queue.h" +#include "freertos/semphr.h" +#include "freertos/task.h" + +#define PROTO_ADDR 0x01 + +#define CMD_POWER 0x00 +#define CMD_GET_STATUS 0x01 +#define CMD_SET_DISTANCE 0x02 +#define CMD_SET_PARAM 0x03 +#define CMD_SEND_DATA 0x04 +#define CMD_GAP_MOVE 0x05 +#define CMD_GET_OFFSET 0x06 +#define CMD_SET_OFFSET 0x07 +#define CMD_BOOT_JUMP_BOOT 0xA0 +#define CMD_BOOT_ERASE_PAGE 0xA1 +#define CMD_BOOT_WRITE_DATA 0xA2 +#define CMD_BOOT_JUMP_APP 0xA3 +#define CMD_BOOT_GET_VERSION 0xA4 + +#define EVT_ACK BIT0 +#define EVT_SHUTDOWN BIT1 +#define EVT_WORKER_EXITED BIT2 +#define EVT_STATUS_POLL_EXITED BIT3 + +#define JOB_QUEUE_LEN 8 +#define JOB_SLOT_MAX 16 +#define MAX_RASTER_BYTES (384 * 3000 / 8) +#define STATUS_POLL_PAUSE_SLOT_MAX 8 +#define PRINTER_JOB_SENTINEL_STOP 0u + +#define OTA_MAX_DATA_PER_FRAME 236u + +typedef struct { + bool used; + bool cancel_requested; + bool direct_ignore_precheck; + uint32_t id; + print_job_state_t state; + uint8_t progress; + uint16_t width; + uint16_t height; + size_t data_len; + char density[16]; + char error[96]; + int64_t created_ms; + int64_t started_ms; + int64_t finished_ms; + uint8_t *data; +} job_slot_t; + +typedef struct { + bool has_paper; + int8_t paper_gpio_level; + uint8_t paper_present_level; + uint8_t battery; + float temperature; + int64_t updated_ms; +} parsed_status_t; + +extern SemaphoreHandle_t s_mutex; +extern QueueHandle_t s_job_queue; +extern EventGroupHandle_t s_evt; +extern uint32_t s_busy_refcnt; +extern parsed_status_t s_status; +extern uint8_t s_last_rsp_cmd; +extern uint16_t s_last_rsp_payload_len; +extern uint8_t s_last_rsp_payload[252]; +extern uint32_t s_status_poll_pause_next_token; +extern uint32_t s_status_poll_pause_tokens[STATUS_POLL_PAUSE_SLOT_MAX]; +extern uint32_t s_next_job_id; +extern job_slot_t s_jobs[JOB_SLOT_MAX]; +extern TaskHandle_t s_worker_task; +extern TaskHandle_t s_status_poll_task_handle; +extern bool s_protocol_initialized; +extern bool s_protocol_stopping; + +bool printer_protocol_acquire_control_lane(uint32_t timeout_ms, char *err, size_t err_len); +void printer_protocol_release_control_lane(void); +esp_err_t printer_protocol_send_cmd_wait_response(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum, + uint32_t timeout_ms, + bool expect_ack, + bool reset_transport_on_timeout, + uint8_t *out_payload, + size_t out_payload_cap, + uint16_t *out_payload_len, + char *err, + size_t err_len); +esp_err_t printer_protocol_send_frame(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum); +bool printer_protocol_wait_response(uint8_t cmd, + uint8_t *out_payload, + size_t out_payload_cap, + uint16_t *out_payload_len, + uint32_t timeout_ms); +bool printer_protocol_send_cmd_with_ack(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum, + uint32_t timeout_ms, + bool reset_transport_on_timeout); + +int printer_protocol_find_job_idx_locked(uint32_t id); +int printer_protocol_alloc_job_slot_locked(void); +bool printer_protocol_is_terminal_state(print_job_state_t state); + +void printer_protocol_worker_task(void *arg); +bool printer_protocol_is_stopping(void); diff --git a/components/domain/internal/voice_interaction_internal.h b/components/domain/internal/voice_interaction_internal.h new file mode 100644 index 0000000..7a2b478 --- /dev/null +++ b/components/domain/internal/voice_interaction_internal.h @@ -0,0 +1,134 @@ +#pragma once + +#include +#include +#include + +#include "esp_opus_dec.h" +#include "esp_opus_enc.h" +#include "esp_websocket_client.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" +#include "freertos/task.h" +#include "domain.h" +#include "platform.h" + +#define VOICE_STREAMING_MODE "duplex" +#define VOICE_TASK_GROUP "aigc" +#define VOICE_TASK_NAME "multimodal-generation" +#define VOICE_FUNCTION_NAME "generation" +#define VOICE_MODEL_NAME "multimodal-dialog" + +#define VOICE_SAMPLE_BYTES 2 +#define VOICE_STATUS_LOCK_TIMEOUT_MS 1000 +#define VOICE_WS_SEND_TIMEOUT_MS 1000 +#define VOICE_WS_TASK_STACK 24576 +#define VOICE_UPLINK_TASK_STACK 32768 +#define VOICE_HEARTBEAT_TASK_STACK 4096 +#define VOICE_START_CONNECT_TIMEOUT_MS 8000 +#define VOICE_AUDIO_IO_TIMEOUT_MS 1200 +#define VOICE_AUDIO_DRAIN_MARGIN_MS 120 +#define VOICE_AUDIO_DRAIN_QUIET_MS 180 +#define VOICE_AUDIO_DRAIN_WAIT_MS 2200 +#define VOICE_AUDIO_DRAIN_WAIT_ON_STOP_MS 3500 + +typedef struct { + SemaphoreHandle_t lock; + esp_websocket_client_handle_t ws; + + TaskHandle_t uplink_task; + TaskHandle_t heartbeat_task; + bool uplink_task_with_caps; + bool heartbeat_task_with_caps; + + void *opus_enc; + void *opus_dec; + int opus_enc_in_size; + int opus_enc_out_size; + + uint8_t *opus_tx_buf; + int16_t *pcm_tx_buf; + + uint8_t *pcm_rx_buf; + size_t pcm_rx_buf_size; + + uint8_t *text_agg; + size_t text_agg_size; + + uint8_t *bin_agg; + size_t bin_agg_size; + + bool ready; + bool session_active; + bool ws_connected; + bool started; + bool tap_active; + bool stop_requested; + bool ws_low_stack_warned; + bool response_first_sentence_checked; + + voice_dialog_state_t dialog_state; + + char task_id[40]; + char dialog_id[40]; + char device_uuid[40]; + char last_error[128]; + + int64_t last_event_ms; + int64_t last_downstream_ms; + int64_t playback_deadline_ms; + uint32_t upstream_packets; + uint32_t downstream_packets; +} voice_context_t; + +extern voice_context_t s_voice; + +int64_t voice_now_ms(void); +void voice_fill_err(char *err, size_t err_len, const char *msg); +void voice_set_last_error_locked(const char *msg); +bool voice_lock(uint32_t timeout_ms); +void voice_unlock(void); +void voice_log_status_snapshot(const char *stage); +void voice_log_heap_snapshot(const char *stage); +void voice_wait_audio_playback_done(uint32_t timeout_ms, const char *stage); +void voice_close_audio_with_drain(uint32_t timeout_ms, const char *stage); + +void *voice_malloc_prefer_psram(size_t size); +void *voice_calloc_prefer_psram(size_t n, size_t size); +void *voice_realloc_prefer_psram(void *ptr, size_t size); + +BaseType_t voice_create_task_prefer_psram(TaskFunction_t task_fn, + const char *name, + uint32_t stack_size, + UBaseType_t priority, + TaskHandle_t *out_task, + bool *out_with_caps); +void voice_delete_task(TaskHandle_t task, bool with_caps); +void voice_delete_self_task(bool with_caps); + +void voice_make_uuid(char out[40]); +void voice_make_device_uuid(char out[40]); +const char *voice_safe_user_id(void); + +esp_err_t voice_setup_opus(char *err, size_t err_len); +esp_err_t voice_open_audio_for_dialog(char *err, size_t err_len); +void voice_release_runtime_resources(void); + +esp_err_t voice_send_directive(const char *action, + const char *directive, + bool with_dialog_id); + +void voice_ws_protocol_handle_text_message(const char *text, size_t len); +void voice_ws_audio_handle_downstream_packet(const uint8_t *data, size_t len); +void voice_marker_try_trigger_image_generation(const char *dialog_id, const char *final_text); +bool voice_marker_image_generation_is_running(void); + +void voice_websocket_event_handler(void *handler_args, + esp_event_base_t base, + int32_t event_id, + void *event_data); + +void voice_interaction_ws_init_cjson_hooks(void); + +void voice_uplink_task(void *arg); +void voice_heartbeat_task(void *arg); diff --git a/components/domain/src/.gitkeep b/components/domain/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/domain/src/domain_runtime_contracts.c b/components/domain/src/domain_runtime_contracts.c new file mode 100644 index 0000000..efe268e --- /dev/null +++ b/components/domain/src/domain_runtime_contracts.c @@ -0,0 +1,201 @@ +#include "domain.h" + +#include + +#include "platform.h" + +static runtime_diag_counter_t to_platform_counter(domain_diag_counter_t counter) { + switch (counter) { + case DOMAIN_DIAG_COUNTER_LIFECYCLE_START_ATTEMPT: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_START_ATTEMPT; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_START_SUCCESS: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_START_SUCCESS; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_START_FAILED: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_START_FAILED; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_START_RETRY: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_START_RETRY; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_ATTEMPT: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_ATTEMPT; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_SUCCESS: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_SUCCESS; + case DOMAIN_DIAG_COUNTER_LIFECYCLE_STOP_FAILED: + return RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_FAILED; + case DOMAIN_DIAG_COUNTER_WIFI_CONNECT_SUCCESS: + return RUNTIME_DIAG_COUNTER_WIFI_CONNECT_SUCCESS; + case DOMAIN_DIAG_COUNTER_WIFI_CONNECT_FAILED: + return RUNTIME_DIAG_COUNTER_WIFI_CONNECT_FAILED; + case DOMAIN_DIAG_COUNTER_WIFI_CONNECT_TIMEOUT: + return RUNTIME_DIAG_COUNTER_WIFI_CONNECT_TIMEOUT; + case DOMAIN_DIAG_COUNTER_PRINTER_JOB_SUBMITTED: + return RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUBMITTED; + case DOMAIN_DIAG_COUNTER_PRINTER_JOB_SUCCESS: + return RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUCCESS; + case DOMAIN_DIAG_COUNTER_PRINTER_JOB_FAILED: + return RUNTIME_DIAG_COUNTER_PRINTER_JOB_FAILED; + case DOMAIN_DIAG_COUNTER_PRINTER_JOB_CANCELED: + return RUNTIME_DIAG_COUNTER_PRINTER_JOB_CANCELED; + case DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_ATTEMPT: + return RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_ATTEMPT; + case DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_SUCCESS: + return RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_SUCCESS; + case DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_FAILED: + return RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_FAILED; + case DOMAIN_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT: + return RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT; + case DOMAIN_DIAG_COUNTER_REST_RESPONSES_TOTAL: + return RUNTIME_DIAG_COUNTER_REST_RESPONSES_TOTAL; + case DOMAIN_DIAG_COUNTER_REST_ERRORS_TOTAL: + return RUNTIME_DIAG_COUNTER_REST_ERRORS_TOTAL; + default: + return RUNTIME_DIAG_COUNTER_MAX; + } +} + +static runtime_diag_gauge_t to_platform_gauge(domain_diag_gauge_t gauge) { + switch (gauge) { + case DOMAIN_DIAG_GAUGE_LIFECYCLE_STATE: + return RUNTIME_DIAG_GAUGE_LIFECYCLE_STATE; + case DOMAIN_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH: + return RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH; + case DOMAIN_DIAG_GAUGE_PRINTER_QUEUE_DEPTH: + return RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH; + default: + return RUNTIME_DIAG_GAUGE_MAX; + } +} + +uint32_t domain_policy_lifecycle_start_retry_count(void) { + return runtime_policy_lifecycle_start_retry_count(); +} + +uint32_t domain_policy_lifecycle_retry_backoff_ms(uint32_t attempt) { + return runtime_policy_lifecycle_retry_backoff_ms(attempt); +} + +bool domain_policy_is_retryable_error(esp_err_t err) { + return runtime_policy_is_retryable_error(err); +} + +uint32_t domain_policy_printer_stop_timeout_ms(void) { + return runtime_policy_printer_stop_timeout_ms(); +} + +uint32_t domain_policy_rest_printer_connect_timeout_ms(void) { + return runtime_policy_rest_printer_connect_timeout_ms(); +} + +uint32_t domain_policy_rest_printer_connect_timeout_min_ms(void) { + return 1000; +} + +uint32_t domain_policy_rest_printer_connect_timeout_max_ms(void) { + return 60000; +} + +uint32_t domain_policy_rest_label_timeout_ms(void) { + return runtime_policy_rest_label_timeout_ms(); +} + +uint32_t domain_policy_rest_label_timeout_min_ms(void) { + return 500; +} + +uint32_t domain_policy_rest_label_timeout_max_ms(void) { + return 30000; +} + +uint32_t domain_policy_rest_ota_timeout_ms(void) { + return runtime_policy_rest_ota_timeout_ms(); +} + +uint32_t domain_policy_rest_ota_timeout_min_ms(void) { + return 500; +} + +uint32_t domain_policy_rest_ota_timeout_max_ms(void) { + return 60000; +} + +uint32_t domain_policy_image_generation_timeout_default_ms(void) { + return runtime_policy_image_generation_timeout_default_ms(); +} + +uint32_t domain_policy_image_generation_timeout_min_ms(void) { + return runtime_policy_image_generation_timeout_min_ms(); +} + +uint32_t domain_policy_image_generation_timeout_max_ms(void) { + return runtime_policy_image_generation_timeout_max_ms(); +} + +uint32_t domain_policy_image_download_timeout_default_ms(void) { + return runtime_policy_image_download_timeout_default_ms(); +} + +uint32_t domain_policy_image_download_timeout_min_ms(void) { + return runtime_policy_image_download_timeout_min_ms(); +} + +uint32_t domain_policy_image_download_timeout_max_ms(void) { + return runtime_policy_image_download_timeout_max_ms(); +} + +void domain_diag_counter_add(domain_diag_counter_t counter, uint32_t delta) { + runtime_diag_counter_t mapped = to_platform_counter(counter); + if (mapped >= RUNTIME_DIAG_COUNTER_MAX) { + return; + } + runtime_diag_counter_add(mapped, delta); +} + +void domain_diag_set_gauge(domain_diag_gauge_t gauge, int32_t value) { + runtime_diag_gauge_t mapped = to_platform_gauge(gauge); + if (mapped >= RUNTIME_DIAG_GAUGE_MAX) { + return; + } + runtime_diag_set_gauge(mapped, value); +} + +void domain_diag_record_error(const char *source, esp_err_t code, const char *message) { + runtime_diag_record_error(source, code, message); +} + +void domain_diag_get_snapshot(domain_diag_snapshot_t *out_snapshot) { + if (out_snapshot == NULL) { + return; + } + + runtime_diag_snapshot_t platform_snapshot = {0}; + runtime_diag_get_snapshot(&platform_snapshot); + + for (int i = 0; i < DOMAIN_DIAG_COUNTER_MAX && i < RUNTIME_DIAG_COUNTER_MAX; ++i) { + out_snapshot->counters[i] = platform_snapshot.counters[i]; + } + for (int i = 0; i < DOMAIN_DIAG_GAUGE_MAX && i < RUNTIME_DIAG_GAUGE_MAX; ++i) { + out_snapshot->gauges[i] = platform_snapshot.gauges[i]; + } + out_snapshot->last_error_ms = platform_snapshot.last_error_ms; + out_snapshot->last_error_code = platform_snapshot.last_error_code; + strlcpy(out_snapshot->last_error_source, + platform_snapshot.last_error_source, + sizeof(out_snapshot->last_error_source)); + strlcpy(out_snapshot->last_error_message, + platform_snapshot.last_error_message, + sizeof(out_snapshot->last_error_message)); +} + +const char *domain_diag_counter_name(domain_diag_counter_t counter) { + runtime_diag_counter_t mapped = to_platform_counter(counter); + if (mapped >= RUNTIME_DIAG_COUNTER_MAX) { + return "unknown"; + } + return runtime_diag_counter_name(mapped); +} + +const char *domain_diag_gauge_name(domain_diag_gauge_t gauge) { + runtime_diag_gauge_t mapped = to_platform_gauge(gauge); + if (mapped >= RUNTIME_DIAG_GAUGE_MAX) { + return "unknown"; + } + return runtime_diag_gauge_name(mapped); +} diff --git a/components/domain/src/image_generation.c b/components/domain/src/image_generation.c new file mode 100644 index 0000000..449faaf --- /dev/null +++ b/components/domain/src/image_generation.c @@ -0,0 +1,962 @@ +#include "domain.h" +#include "platform.h" + +#include +#include +#include + +#include "cJSON.h" +#include "esp_coexist.h" +#include "esp_crt_bundle.h" +#include "esp_heap_caps.h" +#include "esp_http_client.h" +#include "esp_log.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" +#include "freertos/task.h" + +#ifndef CONFIG_TQ_Z_IMAGE_API_ENDPOINT +#define CONFIG_TQ_Z_IMAGE_API_ENDPOINT "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_MODEL +#define CONFIG_TQ_Z_IMAGE_MODEL "z-image-turbo" +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_DEFAULT_SIZE +#define CONFIG_TQ_Z_IMAGE_DEFAULT_SIZE "512*768" +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_TIMEOUT_MS +#define CONFIG_TQ_Z_IMAGE_TIMEOUT_MS 45000 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS +#define CONFIG_TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS 15000 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_MAX_RESPONSE_BYTES +#define CONFIG_TQ_Z_IMAGE_MAX_RESPONSE_BYTES 65536 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_MAX_PNG_BYTES +#define CONFIG_TQ_Z_IMAGE_MAX_PNG_BYTES (4 * 1024 * 1024) +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_HTTP_READ_CHUNK_BYTES +#define CONFIG_TQ_Z_IMAGE_HTTP_READ_CHUNK_BYTES 16384 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_HTTP_BUFFER_BYTES +#define CONFIG_TQ_Z_IMAGE_HTTP_BUFFER_BYTES 16384 +#endif + +#define IMAGE_HTTP_READ_CHUNK_BYTES ((size_t)CONFIG_TQ_Z_IMAGE_HTTP_READ_CHUNK_BYTES) +#define IMAGE_HTTP_BUFFER_BYTES CONFIG_TQ_Z_IMAGE_HTTP_BUFFER_BYTES +#define IMAGE_PREWARM_TIMEOUT_MS 2500 +#define IMAGE_PREWARM_STACK 5120 + +#if CONFIG_FREERTOS_UNICORE +#define IMAGE_WORKER_CORE_ID 0 +#else +#define IMAGE_WORKER_CORE_ID 1 +#endif + +static const char *TAG = "image_generation"; + +typedef struct { + char oss_origin[160]; +} image_prewarm_task_arg_t; + +typedef struct { + uint8_t *data; + size_t len; + size_t cap; + size_t max_len; +} bytes_buffer_t; + +static SemaphoreHandle_t s_prewarm_lock; +static bool s_prewarm_running; +static char s_last_oss_origin[160] = "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/"; + +static bool image_generation_boost_coex_for_download(void) { +#if CONFIG_ESP_COEX_SW_COEXIST_ENABLE && CONFIG_TQ_Z_IMAGE_COEX_PREFER_WIFI_DURING_DOWNLOAD + esp_err_t rc = esp_coex_preference_set(ESP_COEX_PREFER_WIFI); + if (rc != ESP_OK) { + ESP_LOGW(TAG, "failed to prefer Wi-Fi coexist mode, rc=0x%x", (unsigned)rc); + return false; + } + ESP_LOGI(TAG, "coexist prefer Wi-Fi enabled for image download"); + return true; +#else + return false; +#endif +} + +static void image_generation_restore_coex_after_download(bool boosted) { +#if CONFIG_ESP_COEX_SW_COEXIST_ENABLE && CONFIG_TQ_Z_IMAGE_COEX_PREFER_WIFI_DURING_DOWNLOAD + if (!boosted) { + return; + } + esp_err_t rc = esp_coex_preference_set(ESP_COEX_PREFER_BALANCE); + if (rc != ESP_OK) { + ESP_LOGW(TAG, "failed to restore coexist balance mode, rc=0x%x", (unsigned)rc); + return; + } + ESP_LOGI(TAG, "coexist preference restored to balance"); +#else + (void)boosted; +#endif +} + +static void image_generation_fill_err(char *err, size_t err_len, const char *msg) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", msg != NULL ? msg : "unknown error"); + } +} + +static void *malloc_prefer_psram(size_t size) { + void *ptr = heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = malloc(size); + } + return ptr; +} + +static void *realloc_prefer_psram(void *old, size_t size) { + if (old == NULL) { + return malloc_prefer_psram(size); + } + return realloc(old, size); +} + +static esp_err_t bytes_buffer_reserve(bytes_buffer_t *buf, size_t need_extra) { + if (buf == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (need_extra > SIZE_MAX - buf->len) { + return ESP_ERR_INVALID_SIZE; + } + size_t required = buf->len + need_extra; + if (required > buf->max_len) { + return ESP_ERR_INVALID_SIZE; + } + if (required <= buf->cap) { + return ESP_OK; + } + + size_t new_cap = buf->cap == 0 ? 1024 : buf->cap; + while (new_cap < required) { + if (new_cap > (SIZE_MAX / 2)) { + new_cap = required; + break; + } + new_cap *= 2; + } + + uint8_t *new_data = (uint8_t *)realloc_prefer_psram(buf->data, new_cap); + if (new_data == NULL) { + return ESP_ERR_NO_MEM; + } + buf->data = new_data; + buf->cap = new_cap; + return ESP_OK; +} + +static esp_err_t bytes_buffer_append(bytes_buffer_t *buf, const void *data, size_t len) { + if (buf == NULL || data == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (len == 0) { + return ESP_OK; + } + esp_err_t rc = bytes_buffer_reserve(buf, len); + if (rc != ESP_OK) { + return rc; + } + memcpy(buf->data + buf->len, data, len); + buf->len += len; + return ESP_OK; +} + +static void bytes_buffer_free(bytes_buffer_t *buf) { + if (buf == NULL) { + return; + } + free(buf->data); + buf->data = NULL; + buf->len = 0; + buf->cap = 0; +} + +static esp_err_t bytes_buffer_terminate(bytes_buffer_t *buf) { + if (buf == NULL) { + return ESP_ERR_INVALID_ARG; + } + esp_err_t rc = bytes_buffer_reserve(buf, 1); + if (rc != ESP_OK) { + return rc; + } + buf->data[buf->len] = '\0'; + return ESP_OK; +} + +static const char *image_generation_api_key(void) { + if (strlen(CONFIG_TQ_Z_IMAGE_API_KEY) > 0) { + return CONFIG_TQ_Z_IMAGE_API_KEY; + } + if (strlen(CONFIG_TQ_VOICE_API_KEY) > 0) { + return CONFIG_TQ_VOICE_API_KEY; + } + return NULL; +} + +static void prewarm_lock_init_if_needed(void) { + if (s_prewarm_lock != NULL) { + return; + } + s_prewarm_lock = xSemaphoreCreateMutex(); +} + +static bool url_extract_origin(const char *url, char *out_origin, size_t out_origin_len) { + if (url == NULL || out_origin == NULL || out_origin_len == 0) { + return false; + } + + const char *scheme = strstr(url, "://"); + if (scheme == NULL || scheme == url) { + return false; + } + + const char *host = scheme + 3; + if (*host == '\0') { + return false; + } + + const char *path = strchr(host, '/'); + size_t host_len = path != NULL ? (size_t)(path - host) : strlen(host); + if (host_len == 0) { + return false; + } + + int n = snprintf(out_origin, + out_origin_len, + "%.*s://%.*s/", + (int)(scheme - url), + url, + (int)host_len, + host); + return n > 0 && (size_t)n < out_origin_len; +} + +static void image_generation_remember_oss_origin(const char *image_url) { + char origin[160] = {0}; + if (!url_extract_origin(image_url, origin, sizeof(origin))) { + return; + } + + prewarm_lock_init_if_needed(); + if (s_prewarm_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) != pdTRUE) { + return; + } + strlcpy(s_last_oss_origin, origin, sizeof(s_last_oss_origin)); + xSemaphoreGive(s_prewarm_lock); +} + +static void image_generation_copy_oss_origin(char *out_origin, size_t out_origin_len) { + if (out_origin == NULL || out_origin_len == 0) { + return; + } + out_origin[0] = '\0'; + + prewarm_lock_init_if_needed(); + if (s_prewarm_lock == NULL) { + strlcpy(out_origin, s_last_oss_origin, out_origin_len); + return; + } + + if (xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) != pdTRUE) { + strlcpy(out_origin, s_last_oss_origin, out_origin_len); + return; + } + strlcpy(out_origin, s_last_oss_origin, out_origin_len); + xSemaphoreGive(s_prewarm_lock); +} + +static esp_err_t image_generation_http_prewarm_head(const char *url, + const char *auth_header, + uint32_t timeout_ms) { + if (url == NULL || url[0] == '\0') { + return ESP_ERR_INVALID_ARG; + } + + esp_http_client_config_t cfg = { + .url = url, + .method = HTTP_METHOD_HEAD, + .timeout_ms = (int)timeout_ms, + .keep_alive_enable = true, + .buffer_size = 1024, + .buffer_size_tx = 1024, + .crt_bundle_attach = esp_crt_bundle_attach, + }; + + esp_http_client_handle_t client = esp_http_client_init(&cfg); + if (client == NULL) { + return ESP_FAIL; + } + + if (auth_header != NULL && auth_header[0] != '\0') { + esp_http_client_set_header(client, "Authorization", auth_header); + } + + esp_err_t rc = esp_http_client_open(client, 0); + if (rc == ESP_OK) { + (void)esp_http_client_fetch_headers(client); + esp_http_client_close(client); + } + esp_http_client_cleanup(client); + return rc; +} + +static void image_generation_prewarm_task(void *arg) { + image_prewarm_task_arg_t *task_arg = (image_prewarm_task_arg_t *)arg; + char oss_origin[160] = {0}; + if (task_arg != NULL) { + strlcpy(oss_origin, task_arg->oss_origin, sizeof(oss_origin)); + free(task_arg); + } + + int64_t start_ms = esp_timer_get_time() / 1000; + const char *api_key = image_generation_api_key(); + char auth_header[192] = {0}; + const char *auth = NULL; + if (api_key != NULL) { + snprintf(auth_header, sizeof(auth_header), "Bearer %s", api_key); + auth = auth_header; + } + + esp_err_t gen_rc = image_generation_http_prewarm_head(CONFIG_TQ_Z_IMAGE_API_ENDPOINT, + auth, + IMAGE_PREWARM_TIMEOUT_MS); + esp_err_t oss_rc = image_generation_http_prewarm_head(oss_origin, + NULL, + IMAGE_PREWARM_TIMEOUT_MS); + int64_t done_ms = esp_timer_get_time() / 1000; + + ESP_LOGI(TAG, + "https prewarm done, gen_rc=0x%x, oss_rc=0x%x, cost_ms=%lld", + (unsigned)gen_rc, + (unsigned)oss_rc, + (long long)(done_ms - start_ms)); + + prewarm_lock_init_if_needed(); + if (s_prewarm_lock != NULL && xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) == pdTRUE) { + s_prewarm_running = false; + xSemaphoreGive(s_prewarm_lock); + } else { + s_prewarm_running = false; + } + + vTaskDelete(NULL); +} + +void image_generation_schedule_prewarm(void) { + prewarm_lock_init_if_needed(); + if (s_prewarm_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) != pdTRUE) { + return; + } + if (s_prewarm_running) { + xSemaphoreGive(s_prewarm_lock); + return; + } + s_prewarm_running = true; + xSemaphoreGive(s_prewarm_lock); + + image_prewarm_task_arg_t *arg = (image_prewarm_task_arg_t *)malloc_prefer_psram(sizeof(*arg)); + if (arg == NULL) { + if (xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) == pdTRUE) { + s_prewarm_running = false; + xSemaphoreGive(s_prewarm_lock); + } else { + s_prewarm_running = false; + } + return; + } + memset(arg, 0, sizeof(*arg)); + image_generation_copy_oss_origin(arg->oss_origin, sizeof(arg->oss_origin)); + + BaseType_t ok = xTaskCreatePinnedToCore(image_generation_prewarm_task, + "img_prewarm", + IMAGE_PREWARM_STACK, + arg, + 4, + NULL, + IMAGE_WORKER_CORE_ID); + if (ok != pdPASS) { + free(arg); + if (xSemaphoreTake(s_prewarm_lock, pdMS_TO_TICKS(100)) == pdTRUE) { + s_prewarm_running = false; + xSemaphoreGive(s_prewarm_lock); + } else { + s_prewarm_running = false; + } + ESP_LOGW(TAG, "failed to create prewarm task"); + } +} + +static esp_err_t http_read_full_response(esp_http_client_handle_t client, + bytes_buffer_t *out_body, + char *err, + size_t err_len) { + if (client == NULL || out_body == NULL) { + image_generation_fill_err(err, err_len, "invalid http read args"); + return ESP_ERR_INVALID_ARG; + } + + char *tmp = (char *)malloc_prefer_psram(IMAGE_HTTP_READ_CHUNK_BYTES); + if (tmp == NULL) { + image_generation_fill_err(err, err_len, "no memory for http read buffer"); + return ESP_ERR_NO_MEM; + } + + while (true) { + int n = esp_http_client_read(client, tmp, IMAGE_HTTP_READ_CHUNK_BYTES); + if (n < 0) { + free(tmp); + image_generation_fill_err(err, err_len, "http read failed"); + return ESP_FAIL; + } + if (n == 0) { + free(tmp); + if (esp_http_client_is_complete_data_received(client)) { + return ESP_OK; + } + image_generation_fill_err(err, err_len, "http response incomplete"); + return ESP_FAIL; + } + + esp_err_t append_rc = bytes_buffer_append(out_body, tmp, (size_t)n); + if (append_rc != ESP_OK) { + free(tmp); + image_generation_fill_err(err, err_len, "http response too large"); + return append_rc; + } + } +} + +static esp_err_t http_request_collect(const esp_http_client_config_t *config, + const char *auth_header, + const char *body, + int *out_status_code, + bytes_buffer_t *out_body, + char *err, + size_t err_len) { + if (config == NULL || out_body == NULL) { + image_generation_fill_err(err, err_len, "invalid http request args"); + return ESP_ERR_INVALID_ARG; + } + + esp_http_client_handle_t client = esp_http_client_init(config); + if (client == NULL) { + image_generation_fill_err(err, err_len, "http client init failed"); + return ESP_FAIL; + } + + if (auth_header != NULL) { + esp_http_client_set_header(client, "Authorization", auth_header); + } + if (body != NULL) { + esp_http_client_set_header(client, "Content-Type", "application/json"); + } + + size_t body_len = body != NULL ? strlen(body) : 0; + esp_err_t open_rc = esp_http_client_open(client, (int)body_len); + if (open_rc != ESP_OK) { + esp_http_client_cleanup(client); + image_generation_fill_err(err, err_len, "http open failed"); + return open_rc; + } + + if (body != NULL && body_len > 0) { + int written = esp_http_client_write(client, body, (int)body_len); + if (written < 0 || (size_t)written != body_len) { + esp_http_client_close(client); + esp_http_client_cleanup(client); + image_generation_fill_err(err, err_len, "http request write failed"); + return ESP_FAIL; + } + } + + int64_t content_len = esp_http_client_fetch_headers(client); + if (content_len > 0 && (size_t)content_len > out_body->max_len) { + esp_http_client_close(client); + esp_http_client_cleanup(client); + image_generation_fill_err(err, err_len, "http response too large"); + return ESP_ERR_INVALID_SIZE; + } + + if (content_len > 0) { + esp_err_t reserve_rc = bytes_buffer_reserve(out_body, (size_t)content_len); + if (reserve_rc != ESP_OK) { + esp_http_client_close(client); + esp_http_client_cleanup(client); + image_generation_fill_err(err, err_len, "no memory for http response"); + return reserve_rc; + } + } + if (out_status_code != NULL) { + *out_status_code = esp_http_client_get_status_code(client); + } + + esp_err_t read_rc = http_read_full_response(client, out_body, err, err_len); + esp_http_client_close(client); + esp_http_client_cleanup(client); + return read_rc; +} + +static const char *json_get_string(cJSON *obj, const char *name) { + if (obj == NULL || name == NULL) { + return NULL; + } + cJSON *item = cJSON_GetObjectItemCaseSensitive(obj, name); + if (cJSON_IsString(item) && item->valuestring != NULL) { + return item->valuestring; + } + return NULL; +} + +static bool json_extract_image_url(cJSON *root, + char *out_url, + size_t out_url_len, + char *out_prompt, + size_t out_prompt_len) { + if (root == NULL || out_url == NULL || out_url_len == 0) { + return false; + } + + cJSON *output = cJSON_GetObjectItemCaseSensitive(root, "output"); + cJSON *choices = cJSON_GetObjectItemCaseSensitive(output, "choices"); + if (!cJSON_IsArray(choices)) { + return false; + } + + cJSON *choice = cJSON_GetArrayItem(choices, 0); + if (!cJSON_IsObject(choice)) { + return false; + } + + cJSON *message = cJSON_GetObjectItemCaseSensitive(choice, "message"); + cJSON *content = cJSON_GetObjectItemCaseSensitive(message, "content"); + if (!cJSON_IsArray(content)) { + return false; + } + + out_url[0] = '\0'; + if (out_prompt != NULL && out_prompt_len > 0) { + out_prompt[0] = '\0'; + } + + int count = cJSON_GetArraySize(content); + for (int i = 0; i < count; ++i) { + cJSON *item = cJSON_GetArrayItem(content, i); + if (!cJSON_IsObject(item)) { + continue; + } + const char *image = json_get_string(item, "image"); + if (image != NULL && out_url[0] == '\0') { + strlcpy(out_url, image, out_url_len); + } + + if (out_prompt != NULL && out_prompt_len > 0 && out_prompt[0] == '\0') { + const char *text = json_get_string(item, "text"); + if (text != NULL) { + strlcpy(out_prompt, text, out_prompt_len); + } + } + } + + return out_url[0] != '\0'; +} + +static void extract_remote_error_message(const char *json_text, + int status_code, + char *err, + size_t err_len) { + if (json_text == NULL) { + image_generation_fill_err(err, err_len, "upstream request failed"); + return; + } + + cJSON *root = cJSON_Parse(json_text); + if (root == NULL) { + if (status_code > 0) { + snprintf(err, err_len, "upstream request failed, http_status=%d", status_code); + } else { + image_generation_fill_err(err, err_len, "upstream request failed"); + } + return; + } + + const char *code = json_get_string(root, "code"); + const char *message = json_get_string(root, "message"); + + if (code != NULL && message != NULL) { + snprintf(err, err_len, "%s: %s", code, message); + } else if (message != NULL) { + image_generation_fill_err(err, err_len, message); + } else if (status_code > 0) { + snprintf(err, err_len, "upstream request failed, http_status=%d", status_code); + } else { + image_generation_fill_err(err, err_len, "upstream request failed"); + } + + cJSON_Delete(root); +} + +static char *build_generation_request_json(const image_generation_request_t *req) { + cJSON *root = cJSON_CreateObject(); + if (root == NULL) { + return NULL; + } + + cJSON_AddStringToObject(root, "model", CONFIG_TQ_Z_IMAGE_MODEL); + + cJSON *input = cJSON_AddObjectToObject(root, "input"); + cJSON *messages = cJSON_AddArrayToObject(input, "messages"); + cJSON *message = cJSON_CreateObject(); + cJSON_AddItemToArray(messages, message); + cJSON_AddStringToObject(message, "role", "user"); + cJSON *content = cJSON_AddArrayToObject(message, "content"); + cJSON *content_item = cJSON_CreateObject(); + cJSON_AddItemToArray(content, content_item); + cJSON_AddStringToObject(content_item, "text", req->prompt); + + cJSON *parameters = cJSON_AddObjectToObject(root, "parameters"); + cJSON_AddBoolToObject(parameters, "prompt_extend", req->prompt_extend); + + const char *size = (req->size != NULL && req->size[0] != '\0') + ? req->size + : CONFIG_TQ_Z_IMAGE_DEFAULT_SIZE; + cJSON_AddStringToObject(parameters, "size", size); + if (req->has_seed) { + cJSON_AddNumberToObject(parameters, "seed", (double)req->seed); + } + + char *body = cJSON_PrintUnformatted(root); + cJSON_Delete(root); + return body; +} + +static esp_err_t image_generation_invoke_model(const image_generation_request_t *req, + image_generation_result_t *out_result, + char *err, + size_t err_len) { + char *req_body = build_generation_request_json(req); + if (req_body == NULL) { + image_generation_fill_err(err, err_len, "build request json failed"); + return ESP_ERR_NO_MEM; + } + + const char *api_key = image_generation_api_key(); + if (api_key == NULL) { + cJSON_free(req_body); + image_generation_fill_err(err, err_len, "z-image api key not configured"); + return ESP_ERR_INVALID_STATE; + } + + char auth_header[192] = {0}; + snprintf(auth_header, sizeof(auth_header), "Bearer %s", api_key); + + ESP_LOGI(TAG, + "z-image request start, timeout_ms=%u", + (unsigned)req->generation_timeout_ms); + + esp_http_client_config_t config = { + .url = CONFIG_TQ_Z_IMAGE_API_ENDPOINT, + .method = HTTP_METHOD_POST, + .timeout_ms = (int)req->generation_timeout_ms, + .keep_alive_enable = true, + .buffer_size = IMAGE_HTTP_BUFFER_BYTES, + .buffer_size_tx = IMAGE_HTTP_BUFFER_BYTES, + .crt_bundle_attach = esp_crt_bundle_attach, + }; + + bytes_buffer_t resp = { + .data = NULL, + .len = 0, + .cap = 0, + .max_len = CONFIG_TQ_Z_IMAGE_MAX_RESPONSE_BYTES, + }; + int http_status = 0; + esp_err_t rc = http_request_collect(&config, + auth_header, + req_body, + &http_status, + &resp, + err, + err_len); + cJSON_free(req_body); + if (rc != ESP_OK) { + ESP_LOGW(TAG, + "z-image request failed, rc=0x%x, msg=%s", + (unsigned)rc, + (err != NULL && err[0] != '\0') ? err : "http request failed"); + bytes_buffer_free(&resp); + return rc; + } + + rc = bytes_buffer_terminate(&resp); + if (rc != ESP_OK) { + bytes_buffer_free(&resp); + image_generation_fill_err(err, err_len, "generation response too large"); + return rc; + } + + if (http_status < 200 || http_status >= 300) { + extract_remote_error_message((const char *)resp.data, http_status, err, err_len); + ESP_LOGW(TAG, + "z-image http status=%d, msg=%s", + http_status, + (err != NULL && err[0] != '\0') ? err : "upstream request failed"); + bytes_buffer_free(&resp); + return ESP_FAIL; + } + + cJSON *root = cJSON_Parse((const char *)resp.data); + bytes_buffer_free(&resp); + if (root == NULL) { + image_generation_fill_err(err, err_len, "invalid generation response"); + return ESP_FAIL; + } + + const char *request_id = json_get_string(root, "request_id"); + if (request_id != NULL) { + strlcpy(out_result->request_id, request_id, sizeof(out_result->request_id)); + } + + cJSON *usage = cJSON_GetObjectItemCaseSensitive(root, "usage"); + cJSON *usage_w = cJSON_GetObjectItemCaseSensitive(usage, "width"); + cJSON *usage_h = cJSON_GetObjectItemCaseSensitive(usage, "height"); + if (cJSON_IsNumber(usage_w) && usage_w->valuedouble >= 1 && usage_w->valuedouble <= UINT16_MAX) { + out_result->width = (uint16_t)usage_w->valuedouble; + } + if (cJSON_IsNumber(usage_h) && usage_h->valuedouble >= 1 && usage_h->valuedouble <= UINT16_MAX) { + out_result->height = (uint16_t)usage_h->valuedouble; + } + + bool has_url = json_extract_image_url(root, + out_result->image_url, + sizeof(out_result->image_url), + out_result->output_prompt, + sizeof(out_result->output_prompt)); + if (!has_url) { + const char *code = json_get_string(root, "code"); + const char *message = json_get_string(root, "message"); + if (code != NULL && message != NULL) { + snprintf(err, err_len, "%s: %s", code, message); + } else { + image_generation_fill_err(err, err_len, "generation response has no image url"); + } + ESP_LOGW(TAG, + "z-image response parse failed, msg=%s", + (err != NULL && err[0] != '\0') ? err : "generation response has no image url"); + cJSON_Delete(root); + return ESP_FAIL; + } + + image_generation_remember_oss_origin(out_result->image_url); + + ESP_LOGI(TAG, + "z-image response ready, request_id=%s, model_size=%ux%u, image_url_len=%u", + out_result->request_id[0] != '\0' ? out_result->request_id : "-", + (unsigned)out_result->width, + (unsigned)out_result->height, + (unsigned)strlen(out_result->image_url)); + + cJSON_Delete(root); + return ESP_OK; +} + +static esp_err_t image_generation_download_png(image_generation_result_t *out_result, + uint32_t timeout_ms, + char *err, + size_t err_len) { + ESP_LOGI(TAG, "generated image download start, timeout_ms=%u", (unsigned)timeout_ms); + bool coex_boosted = image_generation_boost_coex_for_download(); + + esp_http_client_config_t config = { + .url = out_result->image_url, + .method = HTTP_METHOD_GET, + .timeout_ms = (int)timeout_ms, + .keep_alive_enable = true, + .buffer_size = IMAGE_HTTP_BUFFER_BYTES, + .crt_bundle_attach = esp_crt_bundle_attach, + }; + + bytes_buffer_t resp = { + .data = NULL, + .len = 0, + .cap = 0, + .max_len = CONFIG_TQ_Z_IMAGE_MAX_PNG_BYTES, + }; + int http_status = 0; + esp_err_t rc = http_request_collect(&config, + NULL, + NULL, + &http_status, + &resp, + err, + err_len); + if (rc != ESP_OK) { + ESP_LOGW(TAG, + "generated image download failed, rc=0x%x, msg=%s", + (unsigned)rc, + (err != NULL && err[0] != '\0') ? err : "download failed"); + bytes_buffer_free(&resp); + image_generation_restore_coex_after_download(coex_boosted); + return rc; + } + + if (http_status < 200 || http_status >= 300) { + rc = bytes_buffer_terminate(&resp); + if (rc != ESP_OK) { + bytes_buffer_free(&resp); + image_generation_fill_err(err, err_len, "image download failed"); + image_generation_restore_coex_after_download(coex_boosted); + return ESP_FAIL; + } + extract_remote_error_message((const char *)resp.data, http_status, err, err_len); + ESP_LOGW(TAG, + "generated image download http status=%d, msg=%s", + http_status, + (err != NULL && err[0] != '\0') ? err : "image download failed"); + bytes_buffer_free(&resp); + image_generation_restore_coex_after_download(coex_boosted); + return ESP_FAIL; + } + + static const uint8_t png_header[8] = { + 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, + }; + if (resp.len < sizeof(png_header) || memcmp(resp.data, png_header, sizeof(png_header)) != 0) { + bytes_buffer_free(&resp); + image_generation_fill_err(err, err_len, "downloaded image is not png"); + ESP_LOGW(TAG, "generated image download invalid png signature"); + image_generation_restore_coex_after_download(coex_boosted); + return ESP_FAIL; + } + + out_result->png = resp.data; + out_result->png_len = resp.len; + ESP_LOGI(TAG, "generated image download done, png_bytes=%u", (unsigned)out_result->png_len); + image_generation_restore_coex_after_download(coex_boosted); + return ESP_OK; +} + +void image_generation_result_reset(image_generation_result_t *result) { + if (result == NULL) { + return; + } + memset(result, 0, sizeof(*result)); +} + +void image_generation_result_free(image_generation_result_t *result) { + if (result == NULL) { + return; + } + free(result->png); + result->png = NULL; + result->png_len = 0; +} + +esp_err_t image_generation_generate_png(const image_generation_request_t *req, + image_generation_result_t *out_result, + char *err, + size_t err_len) { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_ATTEMPT, 1); + + if (req == NULL || out_result == NULL || req->prompt == NULL || req->prompt[0] == '\0') { + image_generation_fill_err(err, err_len, "prompt is required"); + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_FAILED, 1); + return ESP_ERR_INVALID_ARG; + } + + image_generation_result_reset(out_result); + + image_generation_request_t actual = *req; + if (actual.generation_timeout_ms == 0) { + actual.generation_timeout_ms = runtime_policy_image_generation_timeout_default_ms(); + } + if (actual.download_timeout_ms == 0) { + actual.download_timeout_ms = runtime_policy_image_download_timeout_default_ms(); + } + + ESP_LOGI(TAG, + "image generate start, prompt_len=%u, size=%s, prompt_extend=%d, seed=%s, gen_timeout_ms=%u, fetch_timeout_ms=%u", + (unsigned)strlen(actual.prompt), + (actual.size != NULL && actual.size[0] != '\0') ? actual.size : "default", + actual.prompt_extend, + actual.has_seed ? "set" : "auto", + (unsigned)actual.generation_timeout_ms, + (unsigned)actual.download_timeout_ms); + + int64_t t0_ms = esp_timer_get_time() / 1000; + esp_err_t gen_rc = image_generation_invoke_model(&actual, out_result, err, err_len); + if (gen_rc != ESP_OK) { + ESP_LOGW(TAG, + "image generate stage failed, rc=0x%x, msg=%s", + (unsigned)gen_rc, + (err != NULL && err[0] != '\0') ? err : "model invoke failed"); + if (gen_rc == ESP_ERR_TIMEOUT) { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT, 1); + } else { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_FAILED, 1); + } + runtime_diag_record_error("image_generate", gen_rc, err != NULL ? err : "model invoke failed"); + image_generation_result_free(out_result); + return gen_rc; + } + + int64_t t_gen_done_ms = esp_timer_get_time() / 1000; + ESP_LOGI(TAG, + "image generate stage done, request_id=%s, gen_cost_ms=%lld", + out_result->request_id[0] != '\0' ? out_result->request_id : "-", + (long long)(t_gen_done_ms - t0_ms)); + esp_err_t dl_rc = image_generation_download_png(out_result, actual.download_timeout_ms, err, err_len); + if (dl_rc != ESP_OK) { + ESP_LOGW(TAG, + "image download stage failed, rc=0x%x, msg=%s", + (unsigned)dl_rc, + (err != NULL && err[0] != '\0') ? err : "download failed"); + if (dl_rc == ESP_ERR_TIMEOUT) { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT, 1); + } else { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_FAILED, 1); + } + runtime_diag_record_error("image_download", dl_rc, err != NULL ? err : "download failed"); + image_generation_result_free(out_result); + return dl_rc; + } + + int64_t t_dl_done_ms = esp_timer_get_time() / 1000; + + ESP_LOGI(TAG, + "image generation pipeline done, request_id=%s, png_bytes=%u, gen_ms=%lld, download_ms=%lld, total_ms=%lld", + out_result->request_id[0] != '\0' ? out_result->request_id : "-", + (unsigned)out_result->png_len, + (long long)(t_gen_done_ms - t0_ms), + (long long)(t_dl_done_ms - t_gen_done_ms), + (long long)(t_dl_done_ms - t0_ms)); + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_SUCCESS, 1); + + return ESP_OK; +} diff --git a/components/domain/src/printer_protocol.c b/components/domain/src/printer_protocol.c new file mode 100644 index 0000000..0bc499d --- /dev/null +++ b/components/domain/src/printer_protocol.c @@ -0,0 +1,1024 @@ +#include "domain.h" +#include "printer_protocol_internal.h" + +#include +#include +#include + +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" + +SemaphoreHandle_t s_mutex; +QueueHandle_t s_job_queue; +EventGroupHandle_t s_evt; + +uint32_t s_busy_refcnt; +uint32_t s_status_poll_pause_next_token; +uint32_t s_status_poll_pause_tokens[STATUS_POLL_PAUSE_SLOT_MAX]; + +parsed_status_t s_status = { + .has_paper = true, + .paper_gpio_level = -1, + .paper_present_level = 0, + .battery = 100, + .temperature = 25.0f, + .updated_ms = 0, +}; + +uint8_t s_last_rsp_cmd; +uint16_t s_last_rsp_payload_len; +uint8_t s_last_rsp_payload[252]; + +uint32_t s_next_job_id = 1; +job_slot_t s_jobs[JOB_SLOT_MAX]; +TaskHandle_t s_worker_task; +TaskHandle_t s_status_poll_task_handle; +bool s_protocol_initialized; +bool s_protocol_stopping; +printer_backend_t s_backend = PRINTER_BACKEND_BLE; +bool s_ble_client_initialized; + +static const char *TAG = "printer_protocol"; + +#if CONFIG_FREERTOS_UNICORE +#define PRINT_WORKER_CORE_ID 0 +#else +#define PRINT_WORKER_CORE_ID 1 +#endif + +static void on_rx_frame(const uint8_t *data, size_t len); + +static printer_backend_t default_backend_on_startup(void) { + // This hardware has a first-class direct path; BLE remains opt-in via API. + if (runtime_policy_direct_printer_enabled()) { + return PRINTER_BACKEND_DIRECT; + } + return PRINTER_BACKEND_BLE; +} + +static void backend_capabilities_for(printer_backend_t backend, printer_capabilities_t *out_caps) { + if (out_caps == NULL) { + return; + } + memset(out_caps, 0, sizeof(*out_caps)); + out_caps->supports_connect = true; + out_caps->supports_gap_move = true; + if (backend == PRINTER_BACKEND_BLE) { + out_caps->supports_label_offset = true; + out_caps->supports_ota = true; + } +} + +static esp_err_t ensure_ble_client_ready(void) { + if (s_ble_client_initialized) { + return ESP_OK; + } + esp_err_t err = ble_printer_client_init(on_rx_frame); + if (err == ESP_OK) { + s_ble_client_initialized = true; + } + return err; +} + +static esp_err_t ensure_backend_ready(printer_backend_t backend) { + if (backend == PRINTER_BACKEND_BLE) { + return ensure_ble_client_ready(); + } + if (backend == PRINTER_BACKEND_DIRECT) { + if (!runtime_policy_direct_printer_enabled()) { + return ESP_ERR_NOT_SUPPORTED; + } + return platform_direct_printer_init(); + } + return ESP_ERR_NOT_SUPPORTED; +} + +static void refresh_direct_status_locked(void) { + if (s_backend != PRINTER_BACKEND_DIRECT) { + return; + } + + platform_printer_sensors_t sensors = {0}; + if (platform_direct_printer_get_sensors(&sensors) == ESP_OK) { + s_status.has_paper = sensors.has_paper; + s_status.paper_gpio_level = sensors.paper_gpio_level; + s_status.paper_present_level = sensors.paper_present_level; + s_status.battery = sensors.battery_percent; + s_status.temperature = sensors.temperature_c; + s_status.updated_ms = sensors.updated_ms; + } +} + +static size_t status_poll_pause_depth_locked(void) { + size_t depth = 0; + for (size_t i = 0; i < STATUS_POLL_PAUSE_SLOT_MAX; ++i) { + if (s_status_poll_pause_tokens[i] != 0) { + ++depth; + } + } + return depth; +} + +static void status_poll_pause_slots_clear_locked(void) { + memset(s_status_poll_pause_tokens, 0, sizeof(s_status_poll_pause_tokens)); +} + +static void reset_jobs_locked(void) { + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + free(s_jobs[i].data); + memset(&s_jobs[i], 0, sizeof(s_jobs[i])); + } + s_next_job_id = 1; +} + +static void reset_runtime_state_locked(void) { + s_busy_refcnt = 0; + s_last_rsp_cmd = 0; + s_last_rsp_payload_len = 0; + memset(s_last_rsp_payload, 0, sizeof(s_last_rsp_payload)); + + status_poll_pause_slots_clear_locked(); + s_status_poll_pause_next_token = 1; + + s_status.has_paper = true; + s_status.paper_gpio_level = -1; + s_status.paper_present_level = 0; + s_status.battery = 100; + s_status.temperature = 25.0f; + s_status.updated_ms = 0; +} + +bool printer_protocol_is_stopping(void) { + if (!s_protocol_initialized) { + return false; + } + if (s_mutex == NULL) { + return true; + } + + bool stopping = true; + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(50)) == pdTRUE) { + stopping = s_protocol_stopping; + xSemaphoreGive(s_mutex); + } + return stopping; +} + +static BaseType_t printer_create_task_prefer_psram(TaskFunction_t task_fn, + const char *name, + uint32_t stack_size, + UBaseType_t priority, + TaskHandle_t *out_task) { +#if defined(CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY) && \ + defined(CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM) && \ + (configSUPPORT_STATIC_ALLOCATION == 1) + BaseType_t rc = xTaskCreatePinnedToCoreWithCaps(task_fn, + name, + (configSTACK_DEPTH_TYPE)stack_size, + NULL, + priority, + out_task, + PRINT_WORKER_CORE_ID, + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (rc == pdPASS) { + return pdPASS; + } +#endif + return xTaskCreatePinnedToCore(task_fn, + name, + (configSTACK_DEPTH_TYPE)stack_size, + NULL, + priority, + out_task, + PRINT_WORKER_CORE_ID); +} + +printer_status_poll_pause_token_t printer_protocol_status_poll_pause_acquire(void) { + if (!s_protocol_initialized || s_mutex == NULL) { + return 0; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) != pdTRUE) { + return 0; + } + + if (s_protocol_stopping) { + xSemaphoreGive(s_mutex); + return 0; + } + + int slot = -1; + for (int i = 0; i < STATUS_POLL_PAUSE_SLOT_MAX; ++i) { + if (s_status_poll_pause_tokens[i] == 0) { + slot = i; + break; + } + } + + if (slot < 0) { + xSemaphoreGive(s_mutex); + ESP_LOGW(TAG, "status poll pause acquire failed: no free slot"); + return 0; + } + + uint32_t token = s_status_poll_pause_next_token++; + if (token == 0) { + token = s_status_poll_pause_next_token++; + } + + s_status_poll_pause_tokens[slot] = token; + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, + (int32_t)status_poll_pause_depth_locked()); + xSemaphoreGive(s_mutex); + return token; +} + +void printer_protocol_status_poll_pause_release(printer_status_poll_pause_token_t *token) { + if (token == NULL || *token == 0) { + return; + } + + if (!s_protocol_initialized || s_mutex == NULL) { + *token = 0; + return; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) != pdTRUE) { + return; + } + + for (int i = 0; i < STATUS_POLL_PAUSE_SLOT_MAX; ++i) { + if (s_status_poll_pause_tokens[i] == *token) { + s_status_poll_pause_tokens[i] = 0; + break; + } + } + + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, + (int32_t)status_poll_pause_depth_locked()); + xSemaphoreGive(s_mutex); + *token = 0; +} + +bool printer_protocol_acquire_control_lane(uint32_t timeout_ms, char *err, size_t err_len) { + if (!s_protocol_initialized || s_mutex == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer protocol not initialized"); + } + return false; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(timeout_ms)) != pdTRUE) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "lock timeout"); + } + return false; + } + + if (s_protocol_stopping) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer protocol stopping"); + } + return false; + } + + if (s_busy_refcnt != 0) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer busy"); + } + return false; + } + + s_busy_refcnt = 1; + xSemaphoreGive(s_mutex); + return true; +} + +void printer_protocol_release_control_lane(void) { + if (s_mutex == NULL) { + return; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000)) != pdTRUE) { + return; + } + + if (s_busy_refcnt > 0) { + --s_busy_refcnt; + } + xSemaphoreGive(s_mutex); +} + +static uint8_t checksum8(const uint8_t *data, size_t len) { + uint32_t sum = 0; + for (size_t i = 0; i < len; ++i) { + sum += data[i]; + } + return (uint8_t)(sum & 0xFF); +} + +esp_err_t printer_protocol_send_frame(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum) { + if (!s_protocol_initialized || printer_protocol_is_stopping()) { + return ESP_ERR_INVALID_STATE; + } + if (s_backend != PRINTER_BACKEND_BLE) { + return ESP_ERR_NOT_SUPPORTED; + } + + uint8_t frame[260]; + size_t total = 4 + payload_len + (with_checksum ? 1 : 0); + if (total > sizeof(frame)) { + return ESP_ERR_INVALID_SIZE; + } + + frame[0] = PROTO_ADDR; + frame[1] = cmd; + frame[2] = (uint8_t)((payload_len >> 8) & 0xFF); + frame[3] = (uint8_t)(payload_len & 0xFF); + + if (payload_len > 0 && payload != NULL) { + memcpy(&frame[4], payload, payload_len); + } + + if (with_checksum) { + frame[4 + payload_len] = checksum8(frame, 4 + payload_len); + } + + return ble_printer_client_write(frame, total); +} + +static void clear_ack_signal(void) { + if (s_evt != NULL) { + xEventGroupClearBits(s_evt, EVT_ACK); + } +} + +bool printer_protocol_wait_response(uint8_t cmd, + uint8_t *out_payload, + size_t out_payload_cap, + uint16_t *out_payload_len, + uint32_t timeout_ms) { + if (timeout_ms == 0 || s_evt == NULL) { + return false; + } + + int64_t deadline = esp_timer_get_time() / 1000 + timeout_ms; + + while (true) { + if (printer_protocol_is_stopping()) { + return false; + } + + int64_t now = esp_timer_get_time() / 1000; + if (now >= deadline) { + return false; + } + + uint32_t wait_ms = (uint32_t)(deadline - now); + if (wait_ms > 100) { + wait_ms = 100; + } + + EventBits_t bits = xEventGroupWaitBits(s_evt, + EVT_ACK | EVT_SHUTDOWN, + pdFALSE, + pdFALSE, + pdMS_TO_TICKS(wait_ms)); + if (bits & EVT_SHUTDOWN) { + return false; + } + + if (!(bits & EVT_ACK)) { + continue; + } + xEventGroupClearBits(s_evt, EVT_ACK); + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) != pdTRUE) { + continue; + } + + uint8_t rsp_cmd = s_last_rsp_cmd; + uint16_t rsp_len = s_last_rsp_payload_len; + uint8_t rsp_copy[sizeof(s_last_rsp_payload)]; + if (rsp_len > sizeof(rsp_copy)) { + rsp_len = sizeof(rsp_copy); + } + if (rsp_len > 0) { + memcpy(rsp_copy, s_last_rsp_payload, rsp_len); + } + xSemaphoreGive(s_mutex); + + if (rsp_cmd == cmd) { + if (out_payload != NULL && out_payload_cap > 0 && rsp_len > 0) { + size_t copy_len = rsp_len; + if (copy_len > out_payload_cap) { + copy_len = out_payload_cap; + } + memcpy(out_payload, rsp_copy, copy_len); + } + if (out_payload_len != NULL) { + *out_payload_len = rsp_len; + } + return true; + } + } +} + +static bool wait_ack(uint8_t cmd, uint32_t timeout_ms) { + uint8_t payload[252]; + uint16_t payload_len = 0; + if (!printer_protocol_wait_response(cmd, payload, sizeof(payload), &payload_len, timeout_ms)) { + return false; + } + return payload_len >= 1 && payload[0] == 0x01; +} + +static void reset_transport_after_timeout(void) { + if (printer_protocol_is_stopping()) { + return; + } + if (printer_protocol_get_backend() == PRINTER_BACKEND_BLE) { + ble_printer_client_disconnect(); + } +} + +bool printer_protocol_send_cmd_with_ack(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum, + uint32_t timeout_ms, + bool reset_transport_on_timeout) { + clear_ack_signal(); + if (printer_protocol_send_frame(cmd, payload, payload_len, with_checksum) != ESP_OK) { + return false; + } + bool ok = wait_ack(cmd, timeout_ms); + if (!ok && reset_transport_on_timeout) { + reset_transport_after_timeout(); + } + return ok; +} + +esp_err_t printer_protocol_send_cmd_wait_response(uint8_t cmd, + const uint8_t *payload, + uint16_t payload_len, + bool with_checksum, + uint32_t timeout_ms, + bool expect_ack, + bool reset_transport_on_timeout, + uint8_t *out_payload, + size_t out_payload_cap, + uint16_t *out_payload_len, + char *err, + size_t err_len) { + clear_ack_signal(); + if (printer_protocol_send_frame(cmd, payload, payload_len, with_checksum) != ESP_OK) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "send frame failed"); + } + return ESP_FAIL; + } + + uint8_t rsp[252]; + uint16_t rsp_len = 0; + if (!printer_protocol_wait_response(cmd, rsp, sizeof(rsp), &rsp_len, timeout_ms)) { + bool stopping = printer_protocol_is_stopping(); + if (!stopping && reset_transport_on_timeout) { + reset_transport_after_timeout(); + } + if (err != NULL && err_len > 0) { + if (stopping) { + snprintf(err, err_len, "protocol stopping"); + } else { + snprintf(err, + err_len, + reset_transport_on_timeout ? "response timeout, transport reset" + : "response timeout"); + } + } + return stopping ? ESP_ERR_INVALID_STATE : ESP_ERR_TIMEOUT; + } + + if (expect_ack && (rsp_len < 1 || rsp[0] != 0x01)) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "cmd 0x%02X rejected", cmd); + } + return ESP_FAIL; + } + + if (out_payload != NULL && out_payload_cap > 0 && rsp_len > 0) { + size_t copy_len = rsp_len; + if (copy_len > out_payload_cap) { + copy_len = out_payload_cap; + } + memcpy(out_payload, rsp, copy_len); + } + if (out_payload_len != NULL) { + *out_payload_len = rsp_len; + } + + return ESP_OK; +} + +static void status_poll_task(void *arg) { + (void)arg; + + while (true) { + bool should_stop = false; + bool can_poll = false; + printer_backend_t backend = PRINTER_BACKEND_BLE; + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(50)) == pdTRUE) { + should_stop = s_protocol_stopping; + can_poll = (s_busy_refcnt == 0) && (status_poll_pause_depth_locked() == 0); + backend = s_backend; + xSemaphoreGive(s_mutex); + } + + if (should_stop) { + break; + } + + if (can_poll) { + if (backend == PRINTER_BACKEND_BLE) { + if (ble_printer_client_is_connected()) { + uint8_t dummy = 0x00; + (void)printer_protocol_send_frame(CMD_GET_STATUS, &dummy, 0, true); + } + } else if (backend == PRINTER_BACKEND_DIRECT) { + if (platform_direct_printer_is_connected() && + xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) == pdTRUE) { + refresh_direct_status_locked(); + xSemaphoreGive(s_mutex); + } + } + } + vTaskDelay(pdMS_TO_TICKS(runtime_policy_printer_status_poll_interval_ms())); + } + + if (s_evt != NULL) { + xEventGroupSetBits(s_evt, EVT_STATUS_POLL_EXITED); + } + s_status_poll_task_handle = NULL; + vTaskDelete(NULL); +} + +static void on_rx_frame(const uint8_t *data, size_t len) { + if (data == NULL || len < 4 || s_mutex == NULL) { + return; + } + + if (data[0] != PROTO_ADDR) { + return; + } + + uint8_t cmd = data[1]; + uint16_t payload_len = ((uint16_t)data[2] << 8) | data[3]; + size_t required = (size_t)payload_len + 4; + if (len < required) { + return; + } + + const uint8_t *payload = &data[4]; + + if (cmd == CMD_GET_STATUS && payload_len >= 5) { + bool has_paper = payload[0] != 0; + uint8_t battery = payload[1]; + int sign = (payload[2] == 0x2D) ? -1 : 1; + int temp_x10 = ((int)payload[3] << 8) | payload[4]; + float temperature = (float)(sign * temp_x10) / 10.0f; + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) == pdTRUE) { + s_status.has_paper = has_paper; + s_status.paper_gpio_level = -1; + s_status.paper_present_level = 0; + s_status.battery = battery; + s_status.temperature = temperature; + s_status.updated_ms = esp_timer_get_time() / 1000; + xSemaphoreGive(s_mutex); + } + return; + } + + if (payload_len >= 1) { + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) == pdTRUE) { + s_last_rsp_cmd = cmd; + s_last_rsp_payload_len = payload_len; + if (s_last_rsp_payload_len > sizeof(s_last_rsp_payload)) { + s_last_rsp_payload_len = sizeof(s_last_rsp_payload); + } + memcpy(s_last_rsp_payload, payload, s_last_rsp_payload_len); + xSemaphoreGive(s_mutex); + } + if (s_evt != NULL) { + xEventGroupSetBits(s_evt, EVT_ACK); + } + } +} + +static void destroy_runtime_objects(void) { + if (s_job_queue != NULL) { + vQueueDelete(s_job_queue); + s_job_queue = NULL; + } + if (s_evt != NULL) { + vEventGroupDelete(s_evt); + s_evt = NULL; + } + if (s_mutex != NULL) { + vSemaphoreDelete(s_mutex); + s_mutex = NULL; + } +} + +esp_err_t printer_protocol_init(void) { + if (s_protocol_initialized) { + return ESP_OK; + } + + s_mutex = xSemaphoreCreateMutex(); + if (s_mutex == NULL) { + return ESP_ERR_NO_MEM; + } + + s_evt = xEventGroupCreate(); + if (s_evt == NULL) { + destroy_runtime_objects(); + return ESP_ERR_NO_MEM; + } + + s_job_queue = xQueueCreate(JOB_QUEUE_LEN, sizeof(uint32_t)); + if (s_job_queue == NULL) { + destroy_runtime_objects(); + return ESP_ERR_NO_MEM; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + reset_jobs_locked(); + reset_runtime_state_locked(); + s_protocol_stopping = false; + xSemaphoreGive(s_mutex); + } + + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, 0); + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, 0); + s_protocol_initialized = true; + s_protocol_stopping = false; + s_ble_client_initialized = false; + s_backend = default_backend_on_startup(); + + esp_err_t err = ensure_backend_ready(s_backend); + if (err != ESP_OK) { + s_protocol_initialized = false; + destroy_runtime_objects(); + return err; + } + + if (s_backend == PRINTER_BACKEND_DIRECT) { + uint32_t connect_timeout_ms = domain_policy_rest_printer_connect_timeout_ms(); + err = platform_direct_printer_connect(connect_timeout_ms); + if (err != ESP_OK) { + s_protocol_initialized = false; + platform_direct_printer_disconnect(); + platform_direct_printer_deinit(); + destroy_runtime_objects(); + return err; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + refresh_direct_status_locked(); + xSemaphoreGive(s_mutex); + } + ESP_LOGI(TAG, "direct printer auto connected at startup"); + } + + BaseType_t ok = printer_create_task_prefer_psram(printer_protocol_worker_task, + "print_worker", + 6144, + 6, + &s_worker_task); + if (ok != pdPASS) { + s_protocol_initialized = false; + destroy_runtime_objects(); + return ESP_ERR_NO_MEM; + } + + ok = printer_create_task_prefer_psram(status_poll_task, + "status_poll", + 4096, + 4, + &s_status_poll_task_handle); + if (ok != pdPASS) { + if (s_worker_task != NULL) { + vTaskDelete(s_worker_task); + s_worker_task = NULL; + } + s_protocol_initialized = false; + destroy_runtime_objects(); + return ESP_ERR_NO_MEM; + } + + ESP_LOGI(TAG, "printer protocol initialized"); + return ESP_OK; +} + +esp_err_t printer_protocol_stop(uint32_t timeout_ms) { + if (!s_protocol_initialized) { + return ESP_OK; + } + + if (timeout_ms == 0) { + timeout_ms = runtime_policy_printer_stop_timeout_ms(); + } + + if (s_mutex != NULL && xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000)) == pdTRUE) { + s_protocol_stopping = true; + s_busy_refcnt = 0; + status_poll_pause_slots_clear_locked(); + xSemaphoreGive(s_mutex); + } + + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, 0); + + if (s_evt != NULL) { + xEventGroupSetBits(s_evt, EVT_SHUTDOWN); + } + + if (s_job_queue != NULL) { + const uint32_t sentinel = PRINTER_JOB_SENTINEL_STOP; + (void)xQueueSend(s_job_queue, &sentinel, 0); + } + + ble_printer_client_disconnect(); + platform_direct_printer_disconnect(); + + bool worker_done = (s_worker_task == NULL); + bool poll_done = (s_status_poll_task_handle == NULL); + + if (s_evt != NULL && (!worker_done || !poll_done)) { + EventBits_t bits = xEventGroupWaitBits(s_evt, + EVT_WORKER_EXITED | EVT_STATUS_POLL_EXITED, + pdFALSE, + pdTRUE, + pdMS_TO_TICKS(timeout_ms)); + worker_done = worker_done || ((bits & EVT_WORKER_EXITED) != 0) || s_worker_task == NULL; + poll_done = poll_done || ((bits & EVT_STATUS_POLL_EXITED) != 0) || s_status_poll_task_handle == NULL; + } + + if (!worker_done && s_worker_task != NULL) { + ESP_LOGW(TAG, "worker task stop timeout, force delete"); + vTaskDelete(s_worker_task); + s_worker_task = NULL; + } + if (!poll_done && s_status_poll_task_handle != NULL) { + ESP_LOGW(TAG, "status poll task stop timeout, force delete"); + vTaskDelete(s_status_poll_task_handle); + s_status_poll_task_handle = NULL; + } + + if (s_mutex != NULL && xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) == pdTRUE) { + reset_jobs_locked(); + reset_runtime_state_locked(); + xSemaphoreGive(s_mutex); + } + + destroy_runtime_objects(); + + s_busy_refcnt = 0; + s_status_poll_pause_next_token = 1; + memset(s_status_poll_pause_tokens, 0, sizeof(s_status_poll_pause_tokens)); + memset(s_last_rsp_payload, 0, sizeof(s_last_rsp_payload)); + s_last_rsp_cmd = 0; + s_last_rsp_payload_len = 0; + s_worker_task = NULL; + s_status_poll_task_handle = NULL; + s_protocol_initialized = false; + s_protocol_stopping = false; + s_ble_client_initialized = false; + s_backend = default_backend_on_startup(); + + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, 0); + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, 0); + + platform_direct_printer_deinit(); + + ESP_LOGI(TAG, "printer protocol stopped"); + return (worker_done && poll_done) ? ESP_OK : ESP_ERR_TIMEOUT; +} + +esp_err_t printer_protocol_set_backend(printer_backend_t backend, char *err, size_t err_len) { + if (backend != PRINTER_BACKEND_BLE && backend != PRINTER_BACKEND_DIRECT) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid backend"); + } + return ESP_ERR_INVALID_ARG; + } + if (backend == PRINTER_BACKEND_DIRECT && !runtime_policy_direct_printer_enabled()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "direct backend disabled"); + } + return ESP_ERR_NOT_SUPPORTED; + } + if (!s_protocol_initialized || s_protocol_stopping || s_mutex == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer protocol unavailable"); + } + return ESP_ERR_INVALID_STATE; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(runtime_policy_printer_control_lock_timeout_ms())) != pdTRUE) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "lock timeout"); + } + return ESP_ERR_TIMEOUT; + } + + printer_backend_t old_backend = s_backend; + if (old_backend == backend) { + xSemaphoreGive(s_mutex); + return ESP_OK; + } + + if (s_busy_refcnt != 0 || (s_job_queue != NULL && uxQueueMessagesWaiting(s_job_queue) > 0)) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer busy"); + } + return ESP_ERR_INVALID_STATE; + } + + s_backend = backend; + xSemaphoreGive(s_mutex); + + ble_printer_client_disconnect(); + platform_direct_printer_disconnect(); + + esp_err_t rc = ensure_backend_ready(backend); + if (rc != ESP_OK) { + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + s_backend = old_backend; + xSemaphoreGive(s_mutex); + } + (void)ensure_backend_ready(old_backend); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "backend init failed"); + } + return rc; + } + + if (backend == PRINTER_BACKEND_DIRECT && xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + refresh_direct_status_locked(); + xSemaphoreGive(s_mutex); + } + return ESP_OK; +} + +printer_backend_t printer_protocol_get_backend(void) { + if (!s_protocol_initialized || s_mutex == NULL) { + return s_backend; + } + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) != pdTRUE) { + return s_backend; + } + printer_backend_t backend = s_backend; + xSemaphoreGive(s_mutex); + return backend; +} + +esp_err_t printer_protocol_connect(const char *target_name, uint32_t timeout_ms) { + printer_connect_options_t opt = { + .backend = printer_protocol_get_backend(), + .name = target_name, + .timeout_ms = timeout_ms, + }; + return printer_protocol_connect_ex(&opt, NULL, 0); +} + +esp_err_t printer_protocol_connect_ex(const printer_connect_options_t *opt, char *err, size_t err_len) { + if (!s_protocol_initialized || s_protocol_stopping) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer protocol unavailable"); + } + return ESP_ERR_INVALID_STATE; + } + + printer_backend_t backend = printer_protocol_get_backend(); + const char *name = NULL; + uint32_t timeout_ms = 0; + if (opt != NULL) { + backend = opt->backend; + name = opt->name; + timeout_ms = opt->timeout_ms; + } + + esp_err_t rc = printer_protocol_set_backend(backend, err, err_len); + if (rc != ESP_OK) { + return rc; + } + + if (backend == PRINTER_BACKEND_BLE) { + rc = ensure_backend_ready(PRINTER_BACKEND_BLE); + if (rc != ESP_OK) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "ble backend unavailable"); + } + return rc; + } + return ble_printer_client_connect(name, timeout_ms); + } + + if (backend == PRINTER_BACKEND_DIRECT) { + rc = ensure_backend_ready(PRINTER_BACKEND_DIRECT); + if (rc != ESP_OK) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "direct backend unavailable"); + } + return rc; + } + return platform_direct_printer_connect(timeout_ms); + } + + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "unsupported backend"); + } + return ESP_ERR_NOT_SUPPORTED; +} + +void printer_protocol_disconnect(void) { + ble_printer_client_disconnect(); + platform_direct_printer_disconnect(); +} + +void printer_protocol_get_capabilities(printer_capabilities_t *out_capabilities) { + if (out_capabilities == NULL) { + return; + } + backend_capabilities_for(printer_protocol_get_backend(), out_capabilities); +} + +void printer_protocol_get_runtime_status(printer_runtime_status_t *out_status) { + if (out_status == NULL) { + return; + } + + memset(out_status, 0, sizeof(*out_status)); + out_status->paper_gpio_level = -1; + out_status->backend = printer_protocol_get_backend(); + + printer_capabilities_t caps = {0}; + backend_capabilities_for(out_status->backend, &caps); + out_status->supports_gap_move = caps.supports_gap_move; + out_status->supports_label_offset = caps.supports_label_offset; + out_status->supports_ota = caps.supports_ota; + + if (out_status->backend == PRINTER_BACKEND_BLE) { + ble_link_state_t link = {0}; + ble_printer_client_get_link_state(&link); + out_status->connected = link.connected; + out_status->notify_ready = link.notify_ready; + out_status->transport_ready = link.connected && link.notify_ready; + out_status->mtu = link.mtu; + } else if (out_status->backend == PRINTER_BACKEND_DIRECT) { + out_status->connected = platform_direct_printer_is_connected(); + out_status->transport_ready = out_status->connected; + out_status->notify_ready = false; + out_status->mtu = 0; + + platform_printer_sensors_t sensors = {0}; + if (platform_direct_printer_get_sensors(&sensors) == ESP_OK && + s_mutex != NULL && + xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) == pdTRUE) { + s_status.has_paper = sensors.has_paper; + s_status.paper_gpio_level = sensors.paper_gpio_level; + s_status.paper_present_level = sensors.paper_present_level; + s_status.battery = sensors.battery_percent; + s_status.temperature = sensors.temperature_c; + s_status.updated_ms = sensors.updated_ms; + xSemaphoreGive(s_mutex); + } + } + + if (s_mutex != NULL && xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + out_status->busy = s_busy_refcnt > 0; + out_status->has_paper = s_status.has_paper; + out_status->paper_gpio_level = s_status.paper_gpio_level; + out_status->paper_present_level = s_status.paper_present_level; + out_status->battery_percent = s_status.battery; + out_status->temperature = s_status.temperature; + out_status->last_status_ms = s_status.updated_ms; + out_status->queue_depth = (s_job_queue != NULL) + ? (uint32_t)uxQueueMessagesWaiting(s_job_queue) + : 0; + xSemaphoreGive(s_mutex); + } + + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, (int32_t)out_status->queue_depth); +} diff --git a/components/domain/src/printer_protocol_commands.c b/components/domain/src/printer_protocol_commands.c new file mode 100644 index 0000000..924210c --- /dev/null +++ b/components/domain/src/printer_protocol_commands.c @@ -0,0 +1,433 @@ +#include "domain.h" +#include "printer_protocol_internal.h" + +#include +#include + +static bool is_direct_backend(void) { + return printer_protocol_get_backend() == PRINTER_BACKEND_DIRECT; +} + +static esp_err_t unsupported_for_direct(char *err, size_t err_len, const char *op) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s not supported on direct backend", op); + } + return ESP_ERR_NOT_SUPPORTED; +} + +static void write_err(char *err, size_t err_len, const char *msg) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", msg); + } +} + +esp_err_t printer_protocol_gap_move(uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return platform_direct_printer_gap_move(timeout_ms, err, err_len); + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + uint8_t payload = 0x01; + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_GAP_MOVE, + &payload, + 1, + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_get_label_offset(uint8_t *out_offset, uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "label offset"); + } + + if (out_offset == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + uint8_t req = 0x01; + uint8_t rsp[16]; + uint16_t rsp_len = 0; + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_GET_OFFSET, + &req, + 1, + true, + timeout_ms, + false, + false, + rsp, + sizeof(rsp), + &rsp_len, + err, + err_len); + printer_protocol_release_control_lane(); + if (rc != ESP_OK) { + return rc; + } + if (rsp_len < 1) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid offset response"); + } + return ESP_FAIL; + } + if (rsp[0] == 0xFF) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "offset unavailable"); + } + return ESP_FAIL; + } + + *out_offset = rsp[0]; + return ESP_OK; +} + +esp_err_t printer_protocol_set_label_offset(uint8_t offset, uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "label offset"); + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_SET_OFFSET, + &offset, + 1, + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_ota_jump_boot(uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "ota jump boot"); + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_BOOT_JUMP_BOOT, + NULL, + 0, + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_ota_jump_app(uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "ota jump app"); + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_BOOT_JUMP_APP, + NULL, + 0, + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_ota_erase_page(uint16_t page_num, uint32_t timeout_ms, char *err, size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "ota erase"); + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + uint8_t payload[2] = { + (uint8_t)((page_num >> 8) & 0xFF), + (uint8_t)(page_num & 0xFF), + }; + + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_BOOT_ERASE_PAGE, + payload, + sizeof(payload), + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_ota_write_frame(uint16_t packet_num, + bool is_last_frame, + const uint8_t *data, + size_t data_len, + uint32_t timeout_ms, + char *err, + size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "ota write"); + } + + if ((data_len > 0 && data == NULL) || data_len > OTA_MAX_DATA_PER_FRAME) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid frame length"); + } + return ESP_ERR_INVALID_ARG; + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + uint8_t payload[3 + OTA_MAX_DATA_PER_FRAME]; + payload[0] = (uint8_t)((packet_num >> 8) & 0xFF); + payload[1] = (uint8_t)(packet_num & 0xFF); + payload[2] = is_last_frame ? 0x01 : 0x00; + if (data_len > 0) { + memcpy(&payload[3], data, data_len); + } + + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_BOOT_WRITE_DATA, + payload, + (uint16_t)(3 + data_len), + true, + timeout_ms, + true, + true, + NULL, + 0, + NULL, + err, + err_len); + printer_protocol_release_control_lane(); + return rc; +} + +esp_err_t printer_protocol_ota_get_version(printer_ota_version_t *out_version, + uint32_t timeout_ms, + char *err, + size_t err_len) { + if (is_direct_backend()) { + return unsupported_for_direct(err, err_len, "ota version"); + } + + if (out_version == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (!ble_printer_client_is_connected()) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer not connected"); + } + return ESP_ERR_INVALID_STATE; + } + + if (!printer_protocol_acquire_control_lane(runtime_policy_printer_control_lock_timeout_ms(), err, err_len)) { + return ESP_ERR_INVALID_STATE; + } + + uint8_t rsp[16]; + uint16_t rsp_len = 0; + esp_err_t rc = printer_protocol_send_cmd_wait_response(CMD_BOOT_GET_VERSION, + NULL, + 0, + true, + timeout_ms, + false, + false, + rsp, + sizeof(rsp), + &rsp_len, + err, + err_len); + printer_protocol_release_control_lane(); + if (rc != ESP_OK) { + return rc; + } + + if (rsp_len < 3) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid version response"); + } + return ESP_FAIL; + } + + out_version->major = rsp[0]; + out_version->minor = rsp[1]; + out_version->patch = rsp[2]; + return ESP_OK; +} + +esp_err_t printer_protocol_get_direct_debug_config(printer_direct_debug_config_t *out_config, + char *err, + size_t err_len) { + if (out_config == NULL) { + write_err(err, err_len, "invalid args"); + return ESP_ERR_INVALID_ARG; + } + if (!runtime_policy_direct_printer_enabled()) { + write_err(err, err_len, "direct backend disabled"); + return ESP_ERR_NOT_SUPPORTED; + } + + esp_err_t rc = platform_direct_printer_get_debug_config(&out_config->shift_clock_high_us, + &out_config->shift_clock_low_us, + &out_config->latch_pulse_us, + &out_config->strobe_active_high, + &out_config->boost_active_high, + &out_config->override_strobe_on_us, + &out_config->override_strobe_interval_us, + &out_config->override_motor_step_us, + &out_config->override_steps_per_line); + if (rc != ESP_OK) { + write_err(err, err_len, "get direct debug config failed"); + return rc; + } + return ESP_OK; +} + +esp_err_t printer_protocol_set_direct_debug_config(const printer_direct_debug_config_t *config, + bool reset_defaults, + char *err, + size_t err_len) { + if (config == NULL && !reset_defaults) { + write_err(err, err_len, "invalid args"); + return ESP_ERR_INVALID_ARG; + } + if (!runtime_policy_direct_printer_enabled()) { + write_err(err, err_len, "direct backend disabled"); + return ESP_ERR_NOT_SUPPORTED; + } + + return platform_direct_printer_set_debug_config(config != NULL, + config != NULL ? config->shift_clock_high_us : 0, + config != NULL ? config->shift_clock_low_us : 0, + config != NULL ? config->latch_pulse_us : 0, + config != NULL ? config->strobe_active_high : false, + config != NULL ? config->boost_active_high : false, + config != NULL ? config->override_strobe_on_us : 0, + config != NULL ? config->override_strobe_interval_us : 0, + config != NULL ? config->override_motor_step_us : 0, + config != NULL ? config->override_steps_per_line : 0, + reset_defaults, + err, + err_len); +} + +const char *printer_protocol_job_state_str(print_job_state_t state) { + switch (state) { + case PRINT_JOB_STATE_NONE: + return "none"; + case PRINT_JOB_STATE_QUEUED: + return "queued"; + case PRINT_JOB_STATE_RUNNING: + return "running"; + case PRINT_JOB_STATE_SUCCESS: + return "success"; + case PRINT_JOB_STATE_FAILED: + return "failed"; + case PRINT_JOB_STATE_CANCELED: + return "canceled"; + default: + return "unknown"; + } +} diff --git a/components/domain/src/printer_protocol_jobs.c b/components/domain/src/printer_protocol_jobs.c new file mode 100644 index 0000000..dcbff03 --- /dev/null +++ b/components/domain/src/printer_protocol_jobs.c @@ -0,0 +1,358 @@ +#include "domain.h" +#include "printer_protocol_internal.h" + +#include +#include +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" + +static const char *TAG = "printer_protocol"; + +int printer_protocol_find_job_idx_locked(uint32_t id) { + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + if (s_jobs[i].used && s_jobs[i].id == id) { + return i; + } + } + return -1; +} + +int printer_protocol_alloc_job_slot_locked(void) { + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + if (!s_jobs[i].used) { + return i; + } + } + + /* Reuse completed slot when table is full. */ + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + if (s_jobs[i].state == PRINT_JOB_STATE_SUCCESS || + s_jobs[i].state == PRINT_JOB_STATE_FAILED || + s_jobs[i].state == PRINT_JOB_STATE_CANCELED) { + free(s_jobs[i].data); + memset(&s_jobs[i], 0, sizeof(s_jobs[i])); + return i; + } + } + + return -1; +} + +bool printer_protocol_is_terminal_state(print_job_state_t state) { + return state == PRINT_JOB_STATE_SUCCESS || + state == PRINT_JOB_STATE_FAILED || + state == PRINT_JOB_STATE_CANCELED; +} + +esp_err_t printer_protocol_submit_raster_job_ex(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + const char *density, + const printer_print_options_t *options, + uint32_t *out_job_id, + char *err, + size_t err_len) { + if (raster == NULL || raster_len == 0 || width == 0 || height == 0) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (!s_protocol_initialized || s_protocol_stopping) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "printer protocol unavailable"); + } + return ESP_ERR_INVALID_STATE; + } + + if (width != 384) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "width must be 384"); + } + return ESP_ERR_INVALID_ARG; + } + + if (raster_len > MAX_RASTER_BYTES) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "raster too large"); + } + return ESP_ERR_INVALID_SIZE; + } + + size_t expected_len = ((size_t)width / 8u) * (size_t)height; + if (expected_len != raster_len) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "size mismatch exp=%u got=%u", + (unsigned)expected_len, + (unsigned)raster_len); + } + return ESP_ERR_INVALID_SIZE; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(runtime_policy_printer_control_lock_timeout_ms())) != pdTRUE) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "lock timeout"); + } + return ESP_ERR_TIMEOUT; + } + + int idx = printer_protocol_alloc_job_slot_locked(); + if (idx < 0) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "job table full"); + } + return ESP_ERR_NO_MEM; + } + + uint8_t *copy = (uint8_t *)malloc(raster_len); + if (copy == NULL) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "malloc failed"); + } + return ESP_ERR_NO_MEM; + } + + memcpy(copy, raster, raster_len); + + uint32_t id = s_next_job_id++; + if (s_next_job_id == 0) { + s_next_job_id = 1; + } + + memset(&s_jobs[idx], 0, sizeof(s_jobs[idx])); + s_jobs[idx].used = true; + s_jobs[idx].id = id; + s_jobs[idx].state = PRINT_JOB_STATE_QUEUED; + s_jobs[idx].progress = 0; + s_jobs[idx].width = width; + s_jobs[idx].height = height; + s_jobs[idx].data_len = raster_len; + s_jobs[idx].direct_ignore_precheck = (options != NULL && options->direct_ignore_precheck); + s_jobs[idx].created_ms = esp_timer_get_time() / 1000; + s_jobs[idx].data = copy; + strlcpy(s_jobs[idx].density, density != NULL ? density : "中等", sizeof(s_jobs[idx].density)); + bool ignore_precheck = s_jobs[idx].direct_ignore_precheck; + + xSemaphoreGive(s_mutex); + + if (xQueueSend(s_job_queue, &id, pdMS_TO_TICKS(500)) != pdTRUE) { + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) == pdTRUE) { + int rollback_idx = printer_protocol_find_job_idx_locked(id); + if (rollback_idx >= 0) { + free(s_jobs[rollback_idx].data); + memset(&s_jobs[rollback_idx], 0, sizeof(s_jobs[rollback_idx])); + } + xSemaphoreGive(s_mutex); + } + + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "job queue full"); + } + ESP_LOGW(TAG, + "job enqueue failed, job_id=%u, reason=%s", + (unsigned)id, + (err != NULL && err[0] != '\0') ? err : "job queue full"); + return ESP_ERR_TIMEOUT; + } + + if (out_job_id != NULL) { + *out_job_id = id; + } + + UBaseType_t queue_depth = uxQueueMessagesWaiting(s_job_queue); + ESP_LOGI(TAG, + "job queued, job_id=%u, raster_bytes=%u, size=%ux%u, density=%s, ignore_precheck=%d, queue_depth=%u", + (unsigned)id, + (unsigned)raster_len, + (unsigned)width, + (unsigned)height, + density != NULL ? density : "中等", + ignore_precheck, + (unsigned)queue_depth); + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUBMITTED, 1); + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, (int32_t)queue_depth); + + return ESP_OK; +} + +esp_err_t printer_protocol_submit_raster_job(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + const char *density, + uint32_t *out_job_id, + char *err, + size_t err_len) { + return printer_protocol_submit_raster_job_ex(raster, + raster_len, + width, + height, + density, + NULL, + out_job_id, + err, + err_len); +} + +bool printer_protocol_get_job(uint32_t job_id, print_job_info_t *out_info) { + if (out_info == NULL || job_id == 0) { + return false; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) != pdTRUE) { + return false; + } + + int idx = printer_protocol_find_job_idx_locked(job_id); + if (idx < 0) { + xSemaphoreGive(s_mutex); + return false; + } + + memset(out_info, 0, sizeof(*out_info)); + + out_info->id = s_jobs[idx].id; + out_info->state = s_jobs[idx].state; + out_info->progress = s_jobs[idx].progress; + out_info->width = s_jobs[idx].width; + out_info->height = s_jobs[idx].height; + out_info->data_len = s_jobs[idx].data_len; + out_info->created_ms = s_jobs[idx].created_ms; + out_info->started_ms = s_jobs[idx].started_ms; + out_info->finished_ms = s_jobs[idx].finished_ms; + strlcpy(out_info->density, s_jobs[idx].density, sizeof(out_info->density)); + strlcpy(out_info->error, s_jobs[idx].error, sizeof(out_info->error)); + + xSemaphoreGive(s_mutex); + return true; +} + +esp_err_t printer_protocol_list_jobs(print_job_info_t *out_jobs, size_t max_jobs, size_t *out_count) { + if (out_count == NULL) { + return ESP_ERR_INVALID_ARG; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) != pdTRUE) { + return ESP_ERR_TIMEOUT; + } + + size_t count = 0; + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + if (!s_jobs[i].used || s_jobs[i].state == PRINT_JOB_STATE_NONE) { + continue; + } + if (out_jobs != NULL && count < max_jobs) { + memset(&out_jobs[count], 0, sizeof(out_jobs[count])); + out_jobs[count].id = s_jobs[i].id; + out_jobs[count].state = s_jobs[i].state; + out_jobs[count].progress = s_jobs[i].progress; + out_jobs[count].width = s_jobs[i].width; + out_jobs[count].height = s_jobs[i].height; + out_jobs[count].data_len = s_jobs[i].data_len; + out_jobs[count].created_ms = s_jobs[i].created_ms; + out_jobs[count].started_ms = s_jobs[i].started_ms; + out_jobs[count].finished_ms = s_jobs[i].finished_ms; + strlcpy(out_jobs[count].density, s_jobs[i].density, sizeof(out_jobs[count].density)); + strlcpy(out_jobs[count].error, s_jobs[i].error, sizeof(out_jobs[count].error)); + } + ++count; + } + + xSemaphoreGive(s_mutex); + *out_count = count; + return ESP_OK; +} + +esp_err_t printer_protocol_cancel_job(uint32_t job_id, char *err, size_t err_len) { + if (job_id == 0) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid job id"); + } + return ESP_ERR_INVALID_ARG; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) != pdTRUE) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "lock timeout"); + } + return ESP_ERR_TIMEOUT; + } + + int idx = printer_protocol_find_job_idx_locked(job_id); + if (idx < 0) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "job not found"); + } + return ESP_ERR_NOT_FOUND; + } + + if (printer_protocol_is_terminal_state(s_jobs[idx].state)) { + xSemaphoreGive(s_mutex); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "job already finished"); + } + return ESP_ERR_INVALID_STATE; + } + + s_jobs[idx].cancel_requested = true; + if (s_jobs[idx].state == PRINT_JOB_STATE_QUEUED) { + s_jobs[idx].state = PRINT_JOB_STATE_CANCELED; + s_jobs[idx].finished_ms = esp_timer_get_time() / 1000; + s_jobs[idx].progress = 0; + strlcpy(s_jobs[idx].error, "job canceled", sizeof(s_jobs[idx].error)); + free(s_jobs[idx].data); + s_jobs[idx].data = NULL; + } else if (s_jobs[idx].state == PRINT_JOB_STATE_RUNNING) { + strlcpy(s_jobs[idx].error, "cancel requested", sizeof(s_jobs[idx].error)); + } + + xSemaphoreGive(s_mutex); + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_CANCELED, 1); + return ESP_OK; +} + +size_t printer_protocol_cleanup_jobs(bool include_success, bool include_failed, bool include_canceled) { + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(500)) != pdTRUE) { + return 0; + } + + size_t removed = 0; + for (int i = 0; i < JOB_SLOT_MAX; ++i) { + if (!s_jobs[i].used) { + continue; + } + + bool match = false; + if (include_success && s_jobs[i].state == PRINT_JOB_STATE_SUCCESS) { + match = true; + } + if (include_failed && s_jobs[i].state == PRINT_JOB_STATE_FAILED) { + match = true; + } + if (include_canceled && s_jobs[i].state == PRINT_JOB_STATE_CANCELED) { + match = true; + } + + if (!match) { + continue; + } + + free(s_jobs[i].data); + memset(&s_jobs[i], 0, sizeof(s_jobs[i])); + ++removed; + } + + xSemaphoreGive(s_mutex); + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, + s_job_queue != NULL ? (int32_t)uxQueueMessagesWaiting(s_job_queue) : 0); + return removed; +} diff --git a/components/domain/src/printer_protocol_worker.c b/components/domain/src/printer_protocol_worker.c new file mode 100644 index 0000000..df44d2e --- /dev/null +++ b/components/domain/src/printer_protocol_worker.c @@ -0,0 +1,464 @@ +#include "domain.h" +#include "printer_protocol_internal.h" + +#include +#include +#include + +#include "esp_log.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" + +static const char *TAG = "printer_protocol"; + +static bool request_status_sync(uint32_t timeout_ms) { + int64_t old_ms; + + if (printer_protocol_get_backend() != PRINTER_BACKEND_BLE) { + return false; + } + + if (printer_protocol_is_stopping()) { + return false; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) != pdTRUE) { + return false; + } + old_ms = s_status.updated_ms; + xSemaphoreGive(s_mutex); + + uint8_t payload = 0x00; + if (printer_protocol_send_frame(CMD_GET_STATUS, &payload, 0, true) != ESP_OK) { + return false; + } + + int64_t deadline = esp_timer_get_time() / 1000 + timeout_ms; + while ((esp_timer_get_time() / 1000) < deadline) { + if (printer_protocol_is_stopping()) { + return false; + } + + vTaskDelay(pdMS_TO_TICKS(20)); + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(100)) != pdTRUE) { + continue; + } + + bool updated = s_status.updated_ms > old_ms; + xSemaphoreGive(s_mutex); + + if (updated) { + return true; + } + } + + return false; +} + +static uint16_t density_to_hot_time(const char *density) { + if (density == NULL) { + return 2000; + } + if (strcmp(density, "较淡") == 0) { + return 1000; + } + if (strcmp(density, "中等") == 0) { + return 1500; + } + if (strcmp(density, "较浓") == 0) { + return 2000; + } + if (strcmp(density, "最深") == 0) { + return 3000; + } + return 2000; +} + +static bool precheck_printer_ready(bool direct_ignore_precheck, char *err, size_t err_len) { + if (printer_protocol_get_backend() == PRINTER_BACKEND_BLE) { + if (!request_status_sync(1200)) { + snprintf(err, err_len, "status timeout"); + return false; + } + + parsed_status_t status; + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) != pdTRUE) { + snprintf(err, err_len, "status lock failed"); + return false; + } + + status = s_status; + xSemaphoreGive(s_mutex); + + if (!status.has_paper) { + snprintf(err, err_len, "printer out of paper"); + return false; + } + + if (status.battery <= 40) { + snprintf(err, err_len, "battery too low"); + return false; + } + + if (status.temperature >= 60.0f) { + snprintf(err, err_len, "temperature too high"); + return false; + } + return true; + } + + if (direct_ignore_precheck) { + return true; + } + + platform_printer_sensors_t sensors = {0}; + if (platform_direct_printer_get_sensors(&sensors) != ESP_OK) { + snprintf(err, err_len, "sensor read failed"); + return false; + } + if (!sensors.has_paper) { + snprintf(err, err_len, "printer out of paper"); + return false; + } + + float temp_min = runtime_policy_direct_printer_temp_min_c(); + float temp_max = runtime_policy_direct_printer_temp_max_c(); + if (temp_max <= temp_min) { + temp_max = temp_min + 1.0f; + } + if (sensors.temperature_c < temp_min || sensors.temperature_c > temp_max) { + snprintf(err, err_len, "temperature out of range"); + return false; + } + + if (sensors.battery_percent < runtime_policy_direct_printer_battery_min_percent()) { + snprintf(err, err_len, "battery too low"); + return false; + } + return true; +} + +static bool run_print_job_ble(job_slot_t *job) { + char err[96]; + err[0] = '\0'; + uint8_t next_progress_log = 25; + + if (!ble_printer_client_is_connected()) { + snprintf(job->error, sizeof(job->error), "printer not connected"); + ESP_LOGW(TAG, "job %u print aborted: %s", (unsigned)job->id, job->error); + return false; + } + + if (!precheck_printer_ready(false, err, sizeof(err))) { + snprintf(job->error, sizeof(job->error), "%s", err); + ESP_LOGW(TAG, "job %u print aborted: %s", (unsigned)job->id, job->error); + return false; + } + + if (job->cancel_requested) { + snprintf(job->error, sizeof(job->error), "job canceled"); + ESP_LOGW(TAG, "job %u print canceled before start", (unsigned)job->id); + return false; + } + + uint8_t power_on = 0x01; + if (!printer_protocol_send_cmd_with_ack(CMD_POWER, &power_on, 1, true, 1500, true)) { + snprintf(job->error, sizeof(job->error), "power on failed"); + ESP_LOGW(TAG, "job %u print aborted: %s", (unsigned)job->id, job->error); + return false; + } + + uint16_t hot_time = density_to_hot_time(job->density); + uint8_t param[4] = { + 0x01, + 0x02, + (uint8_t)((hot_time >> 8) & 0xFF), + (uint8_t)(hot_time & 0xFF), + }; + + if (!printer_protocol_send_cmd_with_ack(CMD_SET_PARAM, param, sizeof(param), true, 1500, true)) { + snprintf(job->error, sizeof(job->error), "set print param failed"); + ESP_LOGW(TAG, "job %u print aborted: %s", (unsigned)job->id, job->error); + return false; + } + + const size_t chunk_max = 240; + size_t total_chunks = (size_t)ceil((double)job->data_len / (double)chunk_max); + ESP_LOGI(TAG, + "job %u data transfer start, chunks=%u, chunk_bytes=%u, hot_time=%u", + (unsigned)job->id, + (unsigned)total_chunks, + (unsigned)chunk_max, + (unsigned)hot_time); + + for (size_t i = 0; i < total_chunks; ++i) { + if (printer_protocol_is_stopping()) { + snprintf(job->error, sizeof(job->error), "protocol stopping"); + return false; + } + + if (job->cancel_requested) { + snprintf(job->error, sizeof(job->error), "job canceled"); + ESP_LOGW(TAG, + "job %u print canceled at chunk %u/%u", + (unsigned)job->id, + (unsigned)(i + 1), + (unsigned)total_chunks); + return false; + } + + size_t start = i * chunk_max; + size_t remain = job->data_len - start; + size_t chunk_len = remain > chunk_max ? chunk_max : remain; + + if (!printer_protocol_send_cmd_with_ack(CMD_SEND_DATA, + &job->data[start], + (uint16_t)chunk_len, + false, + 2500, + true)) { + snprintf(job->error, sizeof(job->error), "send chunk timeout at %u", (unsigned)i); + ESP_LOGW(TAG, "job %u print aborted: %s", (unsigned)job->id, job->error); + return false; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + job->progress = (uint8_t)(((i + 1) * 90) / total_chunks); + if (job->progress < 5) { + job->progress = 5; + } + xSemaphoreGive(s_mutex); + } + + while (job->progress >= next_progress_log && next_progress_log <= 90) { + ESP_LOGI(TAG, + "job %u print progress=%u%% (%u/%u chunks)", + (unsigned)job->id, + (unsigned)job->progress, + (unsigned)(i + 1), + (unsigned)total_chunks); + next_progress_log = (uint8_t)(next_progress_log + 25); + } + } + + ESP_LOGI(TAG, "job %u data transfer done", (unsigned)job->id); + + uint8_t power_off = 0x00; + (void)printer_protocol_send_cmd_with_ack(CMD_POWER, &power_off, 1, true, 1200, false); + + uint8_t feed_payload[3] = {0x2B, 0x00, 0x0C}; + (void)printer_protocol_send_cmd_with_ack(CMD_SET_DISTANCE, + feed_payload, + sizeof(feed_payload), + true, + 1200, + false); + + ESP_LOGI(TAG, "job %u print command sequence done", (unsigned)job->id); + return true; +} + +static bool run_print_job_direct(job_slot_t *job) { + if (!platform_direct_printer_is_connected()) { + snprintf(job->error, sizeof(job->error), "printer not connected"); + return false; + } + + char check_err[96]; + if (!precheck_printer_ready(job->direct_ignore_precheck, check_err, sizeof(check_err))) { + snprintf(job->error, sizeof(job->error), "%s", check_err); + return false; + } + + platform_direct_print_request_t req = { + .width = job->width, + .height = job->height, + .raster = job->data, + .raster_len = job->data_len, + .strobe_on_time_us = density_to_hot_time(job->density), + .strobe_interval_us = runtime_policy_direct_printer_strobe_interval_us(), + .motor_step_delay_us = runtime_policy_direct_printer_motor_step_us(), + .motor_steps_per_line = runtime_policy_direct_printer_steps_per_line(), + .timeout_ms = runtime_policy_direct_printer_operation_timeout_ms(), + .ignore_precheck = job->direct_ignore_precheck, + .cancel_flag = &job->cancel_requested, + }; + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + job->progress = 10; + xSemaphoreGive(s_mutex); + } + + char direct_err[96] = {0}; + esp_err_t rc = platform_direct_printer_print(&req, direct_err, sizeof(direct_err)); + if (rc != ESP_OK) { + if (direct_err[0] != '\0') { + snprintf(job->error, sizeof(job->error), "%s", direct_err); + } else if (rc == ESP_ERR_TIMEOUT) { + snprintf(job->error, sizeof(job->error), "print timeout"); + } else if (rc == ESP_ERR_INVALID_STATE && job->cancel_requested) { + snprintf(job->error, sizeof(job->error), "job canceled"); + } else { + snprintf(job->error, sizeof(job->error), "direct print failed"); + } + return false; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(200)) == pdTRUE) { + job->progress = 95; + xSemaphoreGive(s_mutex); + } + return true; +} + +static bool run_print_job(job_slot_t *job) { + ESP_LOGI(TAG, + "job %u print start, backend=%s, raster_bytes=%u, size=%ux%u, density=%s, ignore_precheck=%d", + (unsigned)job->id, + printer_protocol_get_backend() == PRINTER_BACKEND_BLE ? "ble" : "direct", + (unsigned)job->data_len, + (unsigned)job->width, + (unsigned)job->height, + job->density, + job->direct_ignore_precheck); + + if (printer_protocol_is_stopping()) { + snprintf(job->error, sizeof(job->error), "protocol stopping"); + return false; + } + + if (printer_protocol_get_backend() == PRINTER_BACKEND_BLE) { + return run_print_job_ble(job); + } + return run_print_job_direct(job); +} + +void printer_protocol_worker_task(void *arg) { + (void)arg; + + while (true) { + if (printer_protocol_is_stopping()) { + break; + } + + uint32_t job_id = 0; + if (xQueueReceive(s_job_queue, + &job_id, + pdMS_TO_TICKS(runtime_policy_printer_worker_queue_wait_ms())) != pdTRUE) { + continue; + } + + if (job_id == PRINTER_JOB_SENTINEL_STOP || printer_protocol_is_stopping()) { + break; + } + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000)) != pdTRUE) { + continue; + } + + int idx = printer_protocol_find_job_idx_locked(job_id); + if (idx < 0) { + xSemaphoreGive(s_mutex); + continue; + } + + if (s_jobs[idx].state == PRINT_JOB_STATE_CANCELED) { + free(s_jobs[idx].data); + s_jobs[idx].data = NULL; + if (s_jobs[idx].finished_ms == 0) { + s_jobs[idx].finished_ms = esp_timer_get_time() / 1000; + } + xSemaphoreGive(s_mutex); + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_CANCELED, 1); + continue; + } + + if (s_busy_refcnt != 0) { + xSemaphoreGive(s_mutex); + (void)xQueueSendToFront(s_job_queue, &job_id, 0); + vTaskDelay(pdMS_TO_TICKS(runtime_policy_printer_queue_retry_delay_ms())); + continue; + } + + job_slot_t *job = &s_jobs[idx]; + job->state = PRINT_JOB_STATE_RUNNING; + job->started_ms = esp_timer_get_time() / 1000; + job->progress = 1; + s_busy_refcnt = 1; + int64_t queue_wait_ms = 0; + if (job->started_ms >= job->created_ms) { + queue_wait_ms = job->started_ms - job->created_ms; + } + ESP_LOGI(TAG, + "job %u running, queue_wait_ms=%lld, raster_bytes=%u, size=%ux%u, density=%s", + (unsigned)job->id, + (long long)queue_wait_ms, + (unsigned)job->data_len, + (unsigned)job->width, + (unsigned)job->height, + job->density); + xSemaphoreGive(s_mutex); + + bool ok = run_print_job(job); + + if (xSemaphoreTake(s_mutex, pdMS_TO_TICKS(1000)) != pdTRUE) { + continue; + } + + if (s_busy_refcnt > 0) { + --s_busy_refcnt; + } + s_jobs[idx].finished_ms = esp_timer_get_time() / 1000; + if (s_jobs[idx].state != PRINT_JOB_STATE_CANCELED) { + s_jobs[idx].progress = 100; + } + + if (ok) { + s_jobs[idx].state = PRINT_JOB_STATE_SUCCESS; + s_jobs[idx].error[0] = '\0'; + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUCCESS, 1); + } else if (s_jobs[idx].cancel_requested || printer_protocol_is_stopping()) { + s_jobs[idx].state = PRINT_JOB_STATE_CANCELED; + if (s_jobs[idx].error[0] == '\0') { + strlcpy(s_jobs[idx].error, "job canceled", sizeof(s_jobs[idx].error)); + } + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_CANCELED, 1); + } else { + s_jobs[idx].state = PRINT_JOB_STATE_FAILED; + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_PRINTER_JOB_FAILED, 1); + } + + int64_t duration_ms = 0; + if (s_jobs[idx].finished_ms >= s_jobs[idx].started_ms) { + duration_ms = s_jobs[idx].finished_ms - s_jobs[idx].started_ms; + } + if (s_jobs[idx].state == PRINT_JOB_STATE_SUCCESS) { + ESP_LOGI(TAG, + "job %u done, state=%s, duration_ms=%lld", + (unsigned)s_jobs[idx].id, + printer_protocol_job_state_str(s_jobs[idx].state), + (long long)duration_ms); + } else { + ESP_LOGW(TAG, + "job %u done, state=%s, duration_ms=%lld, error=%s", + (unsigned)s_jobs[idx].id, + printer_protocol_job_state_str(s_jobs[idx].state), + (long long)duration_ms, + s_jobs[idx].error[0] != '\0' ? s_jobs[idx].error : "-"); + } + + free(s_jobs[idx].data); + s_jobs[idx].data = NULL; + runtime_diag_set_gauge(RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, + (int32_t)uxQueueMessagesWaiting(s_job_queue)); + xSemaphoreGive(s_mutex); + } + + if (s_evt != NULL) { + xEventGroupSetBits(s_evt, EVT_WORKER_EXITED); + } + s_worker_task = NULL; + vTaskDelete(NULL); +} diff --git a/components/domain/src/raster_tools.c b/components/domain/src/raster_tools.c new file mode 100644 index 0000000..f2a7092 --- /dev/null +++ b/components/domain/src/raster_tools.c @@ -0,0 +1,467 @@ +#include "domain.h" + +#include +#include +#include +#include + +#define RASTER_WIDTH 384 +#define RASTER_BYTES_PER_ROW (RASTER_WIDTH / 8) +#define CN16_GLYPH_BYTES 32u +#define CN16_INDEX_ENTRY_BYTES 6u +#define UTF8_REPLACEMENT_CODEPOINT 0x003Fu + +extern const uint8_t _binary_cn16_index_bin_start[] asm("_binary_cn16_index_bin_start"); +extern const uint8_t _binary_cn16_index_bin_end[] asm("_binary_cn16_index_bin_end"); +extern const uint8_t _binary_cn16_glyphs_bin_start[] asm("_binary_cn16_glyphs_bin_start"); +extern const uint8_t _binary_cn16_glyphs_bin_end[] asm("_binary_cn16_glyphs_bin_end"); + +/* 5x7 ASCII font table for characters 0x20..0x7E. */ +static const uint8_t font5x7[] = { + 0x00, 0x00, 0x00, 0x00, 0x00, /* space */ + 0x00, 0x00, 0x5F, 0x00, 0x00, /* ! */ + 0x00, 0x07, 0x00, 0x07, 0x00, /* " */ + 0x14, 0x7F, 0x14, 0x7F, 0x14, /* # */ + 0x24, 0x2A, 0x7F, 0x2A, 0x12, /* $ */ + 0x23, 0x13, 0x08, 0x64, 0x62, /* % */ + 0x36, 0x49, 0x55, 0x22, 0x50, /* & */ + 0x00, 0x05, 0x03, 0x00, 0x00, /* ' */ + 0x00, 0x1C, 0x22, 0x41, 0x00, /* ( */ + 0x00, 0x41, 0x22, 0x1C, 0x00, /* ) */ + 0x14, 0x08, 0x3E, 0x08, 0x14, /* * */ + 0x08, 0x08, 0x3E, 0x08, 0x08, /* + */ + 0x00, 0x50, 0x30, 0x00, 0x00, /* , */ + 0x08, 0x08, 0x08, 0x08, 0x08, /* - */ + 0x00, 0x60, 0x60, 0x00, 0x00, /* . */ + 0x20, 0x10, 0x08, 0x04, 0x02, /* / */ + 0x3E, 0x51, 0x49, 0x45, 0x3E, /* 0 */ + 0x00, 0x42, 0x7F, 0x40, 0x00, /* 1 */ + 0x42, 0x61, 0x51, 0x49, 0x46, /* 2 */ + 0x21, 0x41, 0x45, 0x4B, 0x31, /* 3 */ + 0x18, 0x14, 0x12, 0x7F, 0x10, /* 4 */ + 0x27, 0x45, 0x45, 0x45, 0x39, /* 5 */ + 0x3C, 0x4A, 0x49, 0x49, 0x30, /* 6 */ + 0x01, 0x71, 0x09, 0x05, 0x03, /* 7 */ + 0x36, 0x49, 0x49, 0x49, 0x36, /* 8 */ + 0x06, 0x49, 0x49, 0x29, 0x1E, /* 9 */ + 0x00, 0x36, 0x36, 0x00, 0x00, /* : */ + 0x00, 0x56, 0x36, 0x00, 0x00, /* ; */ + 0x08, 0x14, 0x22, 0x41, 0x00, /* < */ + 0x14, 0x14, 0x14, 0x14, 0x14, /* = */ + 0x00, 0x41, 0x22, 0x14, 0x08, /* > */ + 0x02, 0x01, 0x51, 0x09, 0x06, /* ? */ + 0x32, 0x49, 0x79, 0x41, 0x3E, /* @ */ + 0x7E, 0x11, 0x11, 0x11, 0x7E, /* A */ + 0x7F, 0x49, 0x49, 0x49, 0x36, /* B */ + 0x3E, 0x41, 0x41, 0x41, 0x22, /* C */ + 0x7F, 0x41, 0x41, 0x22, 0x1C, /* D */ + 0x7F, 0x49, 0x49, 0x49, 0x41, /* E */ + 0x7F, 0x09, 0x09, 0x09, 0x01, /* F */ + 0x3E, 0x41, 0x49, 0x49, 0x7A, /* G */ + 0x7F, 0x08, 0x08, 0x08, 0x7F, /* H */ + 0x00, 0x41, 0x7F, 0x41, 0x00, /* I */ + 0x20, 0x40, 0x41, 0x3F, 0x01, /* J */ + 0x7F, 0x08, 0x14, 0x22, 0x41, /* K */ + 0x7F, 0x40, 0x40, 0x40, 0x40, /* L */ + 0x7F, 0x02, 0x0C, 0x02, 0x7F, /* M */ + 0x7F, 0x04, 0x08, 0x10, 0x7F, /* N */ + 0x3E, 0x41, 0x41, 0x41, 0x3E, /* O */ + 0x7F, 0x09, 0x09, 0x09, 0x06, /* P */ + 0x3E, 0x41, 0x51, 0x21, 0x5E, /* Q */ + 0x7F, 0x09, 0x19, 0x29, 0x46, /* R */ + 0x46, 0x49, 0x49, 0x49, 0x31, /* S */ + 0x01, 0x01, 0x7F, 0x01, 0x01, /* T */ + 0x3F, 0x40, 0x40, 0x40, 0x3F, /* U */ + 0x1F, 0x20, 0x40, 0x20, 0x1F, /* V */ + 0x7F, 0x20, 0x18, 0x20, 0x7F, /* W */ + 0x63, 0x14, 0x08, 0x14, 0x63, /* X */ + 0x03, 0x04, 0x78, 0x04, 0x03, /* Y */ + 0x61, 0x51, 0x49, 0x45, 0x43, /* Z */ + 0x00, 0x00, 0x7F, 0x41, 0x41, /* [ */ + 0x02, 0x04, 0x08, 0x10, 0x20, /* \\ */ + 0x41, 0x41, 0x7F, 0x00, 0x00, /* ] */ + 0x04, 0x02, 0x01, 0x02, 0x04, /* ^ */ + 0x80, 0x80, 0x80, 0x80, 0x80, /* _ */ + 0x00, 0x03, 0x05, 0x00, 0x00, /* ` */ + 0x20, 0x54, 0x54, 0x54, 0x78, /* a */ + 0x7F, 0x48, 0x44, 0x44, 0x38, /* b */ + 0x38, 0x44, 0x44, 0x44, 0x20, /* c */ + 0x38, 0x44, 0x44, 0x48, 0x7F, /* d */ + 0x38, 0x54, 0x54, 0x54, 0x18, /* e */ + 0x08, 0x7E, 0x09, 0x01, 0x02, /* f */ + 0x0C, 0x52, 0x52, 0x52, 0x3E, /* g */ + 0x7F, 0x08, 0x04, 0x04, 0x78, /* h */ + 0x00, 0x44, 0x7D, 0x40, 0x00, /* i */ + 0x20, 0x40, 0x44, 0x3D, 0x00, /* j */ + 0x7F, 0x10, 0x28, 0x44, 0x00, /* k */ + 0x00, 0x41, 0x7F, 0x40, 0x00, /* l */ + 0x7C, 0x04, 0x18, 0x04, 0x78, /* m */ + 0x7C, 0x08, 0x04, 0x04, 0x78, /* n */ + 0x38, 0x44, 0x44, 0x44, 0x38, /* o */ + 0x7C, 0x14, 0x14, 0x14, 0x08, /* p */ + 0x08, 0x14, 0x14, 0x18, 0x7C, /* q */ + 0x7C, 0x08, 0x04, 0x04, 0x08, /* r */ + 0x48, 0x54, 0x54, 0x54, 0x20, /* s */ + 0x04, 0x3F, 0x44, 0x40, 0x20, /* t */ + 0x3C, 0x40, 0x40, 0x20, 0x7C, /* u */ + 0x1C, 0x20, 0x40, 0x20, 0x1C, /* v */ + 0x3C, 0x40, 0x30, 0x40, 0x3C, /* w */ + 0x44, 0x28, 0x10, 0x28, 0x44, /* x */ + 0x0C, 0x50, 0x50, 0x50, 0x3C, /* y */ + 0x44, 0x64, 0x54, 0x4C, 0x44, /* z */ + 0x00, 0x08, 0x36, 0x41, 0x00, /* { */ + 0x00, 0x00, 0x7F, 0x00, 0x00, /* | */ + 0x00, 0x41, 0x36, 0x08, 0x00, /* } */ + 0x08, 0x08, 0x2A, 0x1C, 0x08 /* ~ */ +}; + +static void set_black(uint8_t *buf, uint16_t width, uint16_t x, uint16_t y) { + if (x >= width) { + return; + } + uint16_t bpr = width / 8; + size_t idx = (size_t)y * bpr + (x / 8); + uint8_t bit = (uint8_t)(7 - (x % 8)); + buf[idx] |= (uint8_t)(1u << bit); +} + +static size_t cn16_index_count(void) { + size_t bytes = (size_t)(_binary_cn16_index_bin_end - _binary_cn16_index_bin_start); + return bytes / CN16_INDEX_ENTRY_BYTES; +} + +static bool cn16_read_index_entry(size_t idx, uint32_t *out_cp, uint16_t *out_gid) { + if (out_cp == NULL || out_gid == NULL) { + return false; + } + size_t count = cn16_index_count(); + if (idx >= count) { + return false; + } + + const uint8_t *p = _binary_cn16_index_bin_start + idx * CN16_INDEX_ENTRY_BYTES; + *out_cp = ((uint32_t)p[0]) | + ((uint32_t)p[1] << 8) | + ((uint32_t)p[2] << 16) | + ((uint32_t)p[3] << 24); + *out_gid = (uint16_t)(p[4] | ((uint16_t)p[5] << 8)); + return true; +} + +static bool cn16_lookup_glyph(uint32_t codepoint, const uint8_t **out_glyph) { + if (out_glyph == NULL) { + return false; + } + + size_t count = cn16_index_count(); + if (count == 0) { + return false; + } + + size_t lo = 0; + size_t hi = count; + while (lo < hi) { + size_t mid = lo + ((hi - lo) / 2); + uint32_t cp = 0; + uint16_t gid = 0; + if (!cn16_read_index_entry(mid, &cp, &gid)) { + return false; + } + + if (cp == codepoint) { + size_t glyph_bytes = (size_t)(_binary_cn16_glyphs_bin_end - + _binary_cn16_glyphs_bin_start); + size_t off = (size_t)gid * CN16_GLYPH_BYTES; + if ((off + CN16_GLYPH_BYTES) > glyph_bytes) { + return false; + } + *out_glyph = _binary_cn16_glyphs_bin_start + off; + return true; + } + if (cp < codepoint) { + lo = mid + 1; + } else { + hi = mid; + } + } + + return false; +} + +static void draw_char(uint8_t *buf, + uint16_t width, + uint16_t height, + uint16_t x, + uint16_t y, + char ch, + uint8_t scale) { + if (ch < 32 || ch > 126) { + ch = '?'; + } + + const uint8_t *glyph = &font5x7[(ch - 32) * 5]; + for (uint8_t col = 0; col < 5; ++col) { + uint8_t bits = glyph[col]; + for (uint8_t row = 0; row < 7; ++row) { + if (((bits >> row) & 0x01u) == 0) { + continue; + } + for (uint8_t sx = 0; sx < scale; ++sx) { + for (uint8_t sy = 0; sy < scale; ++sy) { + uint16_t px = (uint16_t)(x + col * scale + sx); + uint16_t py = (uint16_t)(y + row * scale + sy); + if (py < height) { + set_black(buf, width, px, py); + } + } + } + } + } +} + +static void draw_cn16_glyph(uint8_t *buf, + uint16_t width, + uint16_t height, + uint16_t x, + uint16_t y, + const uint8_t *glyph, + uint8_t scale) { + if (glyph == NULL || scale == 0) { + return; + } + + for (uint8_t row = 0; row < 16; ++row) { + uint16_t bits = ((uint16_t)glyph[row * 2] << 8) | glyph[row * 2 + 1]; + for (uint8_t col = 0; col < 16; ++col) { + if ((bits & (uint16_t)(1u << (15 - col))) == 0) { + continue; + } + for (uint8_t sx = 0; sx < scale; ++sx) { + for (uint8_t sy = 0; sy < scale; ++sy) { + uint16_t px = (uint16_t)(x + col * scale + sx); + uint16_t py = (uint16_t)(y + row * scale + sy); + if (py < height && px < width) { + set_black(buf, width, px, py); + } + } + } + } + } +} + +static void draw_missing_box(uint8_t *buf, + uint16_t width, + uint16_t height, + uint16_t x, + uint16_t y, + uint8_t scale) { + uint16_t box = (uint16_t)(16 * scale); + for (uint16_t r = 0; r < box; ++r) { + for (uint16_t c = 0; c < box; ++c) { + bool edge = (r < scale) || (c < scale) || (r >= box - scale) || (c >= box - scale); + if (!edge) { + continue; + } + uint16_t px = (uint16_t)(x + c); + uint16_t py = (uint16_t)(y + r); + if (px < width && py < height) { + set_black(buf, width, px, py); + } + } + } +} + +static uint32_t utf8_decode_one(const unsigned char *s, size_t len, size_t *out_consumed) { + if (out_consumed == NULL || s == NULL || len == 0) { + return UTF8_REPLACEMENT_CODEPOINT; + } + + uint8_t b0 = s[0]; + if (b0 < 0x80) { + *out_consumed = 1; + return b0; + } + + if ((b0 & 0xE0u) == 0xC0u && len >= 2) { + uint8_t b1 = s[1]; + if ((b1 & 0xC0u) == 0x80u) { + uint32_t cp = ((uint32_t)(b0 & 0x1Fu) << 6) | + (uint32_t)(b1 & 0x3Fu); + if (cp >= 0x80u) { + *out_consumed = 2; + return cp; + } + } + } else if ((b0 & 0xF0u) == 0xE0u && len >= 3) { + uint8_t b1 = s[1]; + uint8_t b2 = s[2]; + if ((b1 & 0xC0u) == 0x80u && (b2 & 0xC0u) == 0x80u) { + uint32_t cp = ((uint32_t)(b0 & 0x0Fu) << 12) | + ((uint32_t)(b1 & 0x3Fu) << 6) | + (uint32_t)(b2 & 0x3Fu); + if (cp >= 0x800u && !(cp >= 0xD800u && cp <= 0xDFFFu)) { + *out_consumed = 3; + return cp; + } + } + } else if ((b0 & 0xF8u) == 0xF0u && len >= 4) { + uint8_t b1 = s[1]; + uint8_t b2 = s[2]; + uint8_t b3 = s[3]; + if ((b1 & 0xC0u) == 0x80u && (b2 & 0xC0u) == 0x80u && (b3 & 0xC0u) == 0x80u) { + uint32_t cp = ((uint32_t)(b0 & 0x07u) << 18) | + ((uint32_t)(b1 & 0x3Fu) << 12) | + ((uint32_t)(b2 & 0x3Fu) << 6) | + (uint32_t)(b3 & 0x3Fu); + if (cp >= 0x10000u && cp <= 0x10FFFFu) { + *out_consumed = 4; + return cp; + } + } + } + + *out_consumed = 1; + return UTF8_REPLACEMENT_CODEPOINT; +} + +esp_err_t raster_tools_render_text_384(const char *text, + uint8_t scale, + uint8_t line_spacing, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len) { + if (text == NULL || out_width == NULL || out_height == NULL || + out_raster == NULL || out_len == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (scale == 0) { + scale = 1; + } + + if (max_height == 0 || max_height > 3000) { + max_height = 3000; + } + + size_t full_len = (size_t)RASTER_BYTES_PER_ROW * max_height; + uint8_t *buf = (uint8_t *)calloc(1, full_len); + if (buf == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + uint16_t cursor_x = 0; + uint16_t cursor_y = 0; + uint16_t ascii_w = (uint16_t)(6 * scale); + uint16_t ascii_h = (uint16_t)(7 * scale); + uint16_t cjk_w = (uint16_t)(16 * scale); + uint16_t cjk_h = (uint16_t)(16 * scale); + uint16_t line_h = (uint16_t)(cjk_h + line_spacing * scale); + if (line_h == 0) { + line_h = cjk_h; + } + + uint16_t used_bottom = 0; + bool truncated = false; + + const unsigned char *p = (const unsigned char *)text; + size_t remain = strlen(text); + while (remain > 0) { + size_t consumed = 0; + uint32_t cp = utf8_decode_one(p, remain, &consumed); + if (consumed == 0) { + break; + } + p += consumed; + remain -= consumed; + + if (cp == '\r') { + continue; + } + if (cp == '\n') { + cursor_x = 0; + cursor_y = (uint16_t)(cursor_y + line_h); + continue; + } + + bool is_ascii = cp >= 0x20u && cp <= 0x7Eu; + uint16_t draw_w = is_ascii ? ascii_w : cjk_w; + uint16_t draw_h = is_ascii ? ascii_h : cjk_h; + uint16_t draw_y = cursor_y; + if (is_ascii && cjk_h > ascii_h) { + draw_y = (uint16_t)(cursor_y + (cjk_h - ascii_h) / 2); + } + + if ((uint16_t)(cursor_x + draw_w) > RASTER_WIDTH) { + cursor_x = 0; + cursor_y = (uint16_t)(cursor_y + line_h); + draw_y = cursor_y; + if (is_ascii && cjk_h > ascii_h) { + draw_y = (uint16_t)(cursor_y + (cjk_h - ascii_h) / 2); + } + } + + if ((uint16_t)(draw_y + draw_h) > max_height) { + truncated = true; + break; + } + + if (is_ascii) { + draw_char(buf, RASTER_WIDTH, max_height, cursor_x, draw_y, (char)cp, scale); + } else { + const uint8_t *glyph = NULL; + if (cn16_lookup_glyph(cp, &glyph)) { + draw_cn16_glyph(buf, RASTER_WIDTH, max_height, cursor_x, draw_y, glyph, scale); + } else { + draw_missing_box(buf, RASTER_WIDTH, max_height, cursor_x, draw_y, scale); + } + } + cursor_x = (uint16_t)(cursor_x + draw_w); + + uint16_t bottom = (uint16_t)(draw_y + draw_h); + if (bottom > used_bottom) { + used_bottom = bottom; + } + } + + if (used_bottom == 0) { + used_bottom = cjk_h; + } + + if (used_bottom > max_height) { + used_bottom = max_height; + } + + size_t final_len = (size_t)RASTER_BYTES_PER_ROW * used_bottom; + uint8_t *final_buf = (uint8_t *)malloc(final_len); + if (final_buf == NULL) { + free(buf); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + memcpy(final_buf, buf, final_len); + free(buf); + + *out_width = RASTER_WIDTH; + *out_height = used_bottom; + *out_raster = final_buf; + *out_len = final_len; + + if (truncated && err != NULL && err_len > 0) { + snprintf(err, err_len, "text truncated due to max height"); + } + + return ESP_OK; +} diff --git a/components/domain/src/raster_tools_image_qr.c b/components/domain/src/raster_tools_image_qr.c new file mode 100644 index 0000000..3658234 --- /dev/null +++ b/components/domain/src/raster_tools_image_qr.c @@ -0,0 +1,531 @@ +#include "domain.h" + +#include +#include +#include +#include + +#include "esp_heap_caps.h" +#include "png.h" +#include "qrcodegen.h" + +#define RASTER_WIDTH 384 +#define RASTER_BYTES_PER_ROW (RASTER_WIDTH / 8) +#define PNG_DECODE_MAX_BYTES (2 * 1024 * 1024) +#define PNG_DECODE_MAX_WIDTH 1600 + +static const uint8_t s_bit_mask[8] = {0x80u, 0x40u, 0x20u, 0x10u, 0x08u, 0x04u, 0x02u, 0x01u}; + +static void set_black(uint8_t *buf, uint16_t width, uint16_t x, uint16_t y) { + if (x >= width) { + return; + } + uint16_t bpr = width / 8; + size_t idx = (size_t)y * bpr + (x / 8); + uint8_t bit = (uint8_t)(7 - (x % 8)); + buf[idx] |= (uint8_t)(1u << bit); +} + +static void *alloc_prefer_psram(size_t size) { + void *ptr = heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = malloc(size); + } + return ptr; +} + +static void *calloc_prefer_psram(size_t n, size_t size) { + void *ptr = heap_caps_calloc(n, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = calloc(n, size); + } + return ptr; +} + +static uint8_t gray8_to_work_luma(uint8_t gray, bool invert) { + return invert ? (uint8_t)(255u - gray) : gray; +} + +static uint8_t compute_otsu_threshold(const uint32_t hist[256], uint32_t total_count) { + if (hist == NULL || total_count == 0) { + return 160; + } + + uint64_t all_sum = 0; + for (uint32_t i = 0; i < 256; ++i) { + all_sum += (uint64_t)i * hist[i]; + } + + uint64_t bg_sum = 0; + uint32_t bg_count = 0; + double max_between_var = -1.0; + uint8_t best_thr = 160; + + for (uint32_t t = 0; t < 256; ++t) { + bg_count += hist[t]; + if (bg_count == 0) { + continue; + } + + uint32_t fg_count = total_count - bg_count; + if (fg_count == 0) { + break; + } + + bg_sum += (uint64_t)t * hist[t]; + double bg_mean = (double)bg_sum / (double)bg_count; + double fg_mean = (double)(all_sum - bg_sum) / (double)fg_count; + double mean_diff = bg_mean - fg_mean; + double between_var = (double)bg_count * (double)fg_count * mean_diff * mean_diff; + + if (between_var > max_between_var) { + max_between_var = between_var; + best_thr = (uint8_t)t; + } + } + + return best_thr; +} + +esp_err_t raster_tools_convert_gray8_to_raster_384(const uint8_t *gray, + uint16_t src_width, + uint16_t src_height, + bool scale_to_width, + uint8_t threshold, + bool invert, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len) { + if (gray == NULL || src_width == 0 || src_height == 0 || + out_width == NULL || out_height == NULL || out_raster == NULL || out_len == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (max_height == 0 || max_height > 3000) { + max_height = 3000; + } + + uint16_t dst_width = RASTER_WIDTH; + uint16_t dst_height = src_height; + if (scale_to_width) { + if (src_width == 0) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid source width"); + } + return ESP_ERR_INVALID_ARG; + } + uint32_t scaled = ((uint32_t)src_height * RASTER_WIDTH + (src_width / 2u)) / src_width; + if (scaled == 0) { + scaled = 1; + } + if (scaled > max_height) { + scaled = max_height; + } + dst_height = (uint16_t)scaled; + } else if (src_width != RASTER_WIDTH) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "width must be 384 when scale_to_width=false"); + } + return ESP_ERR_INVALID_ARG; + } + + if (dst_height == 0 || dst_height > max_height) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid output height"); + } + return ESP_ERR_INVALID_SIZE; + } + + uint16_t *x_map = (uint16_t *)alloc_prefer_psram(sizeof(uint16_t) * RASTER_WIDTH); + uint16_t *y_map = (uint16_t *)alloc_prefer_psram(sizeof(uint16_t) * dst_height); + size_t total_px = (size_t)RASTER_WIDTH * dst_height; + uint8_t *luma = (uint8_t *)alloc_prefer_psram(total_px); + if (x_map == NULL || y_map == NULL || luma == NULL) { + free(x_map); + free(y_map); + free(luma); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + for (uint16_t x = 0; x < RASTER_WIDTH; ++x) { + uint16_t src_x = scale_to_width + ? (uint16_t)(((uint32_t)x * src_width) / RASTER_WIDTH) + : x; + if (src_x >= src_width) { + src_x = (uint16_t)(src_width - 1); + } + x_map[x] = src_x; + } + for (uint16_t y = 0; y < dst_height; ++y) { + uint16_t src_y = scale_to_width + ? (uint16_t)(((uint32_t)y * src_height) / dst_height) + : y; + if (src_y >= src_height) { + src_y = (uint16_t)(src_height - 1); + } + y_map[y] = src_y; + } + + size_t len = (size_t)RASTER_BYTES_PER_ROW * dst_height; + uint8_t *raster = (uint8_t *)calloc_prefer_psram(1, len); + if (raster == NULL) { + free(x_map); + free(y_map); + free(luma); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + uint32_t hist[256] = {0}; + uint64_t sum_luma = 0; + for (uint16_t y = 0; y < dst_height; ++y) { + const uint8_t *src_row = gray + (size_t)y_map[y] * src_width; + uint8_t *dst_luma_row = luma + (size_t)y * RASTER_WIDTH; + for (uint16_t x = 0; x < RASTER_WIDTH; ++x) { + uint8_t src_v = src_row[x_map[x]]; + uint8_t work_v = gray8_to_work_luma(src_v, invert); + dst_luma_row[x] = work_v; + hist[work_v]++; + sum_luma += work_v; + } + } + + uint8_t otsu_thr = compute_otsu_threshold(hist, (uint32_t)total_px); + uint8_t mean_luma = total_px > 0 ? (uint8_t)(sum_luma / total_px) : (uint8_t)160; + + /* Keep backward compatibility: threshold still works as bias around 160. */ + int final_thr = (int)otsu_thr + (((int)threshold - 160) / 2); + /* White-bias to reduce large black blocks on thermal paper. */ + if (mean_luma < 112) { + final_thr -= 10; + } else if (mean_luma > 182) { + final_thr += 6; + } + if (final_thr < 40) { + final_thr = 40; + } else if (final_thr > 220) { + final_thr = 220; + } + + int16_t *err_curr = (int16_t *)calloc_prefer_psram(RASTER_WIDTH + 2u, sizeof(int16_t)); + int16_t *err_next = (int16_t *)calloc_prefer_psram(RASTER_WIDTH + 2u, sizeof(int16_t)); + bool use_dither = (err_curr != NULL && err_next != NULL); + + for (uint16_t y = 0; y < dst_height; ++y) { + const uint8_t *luma_row = luma + (size_t)y * RASTER_WIDTH; + uint8_t *raster_row = raster + (size_t)y * RASTER_BYTES_PER_ROW; + for (uint16_t x = 0; x < RASTER_WIDTH; ++x) { + int px_luma = (int)luma_row[x]; + if (use_dither) { + px_luma += err_curr[x + 1u]; + if (px_luma < 0) { + px_luma = 0; + } else if (px_luma > 255) { + px_luma = 255; + } + } + + bool black = px_luma < final_thr; + if (black) { + raster_row[x >> 3] |= s_bit_mask[x & 7u]; + } + + if (use_dither) { + int quantized = black ? 0 : 255; + int e = px_luma - quantized; + + if ((x + 1u) < RASTER_WIDTH) { + err_curr[x + 2u] += (int16_t)((e * 7) / 16); + } + err_next[x] += (int16_t)((e * 3) / 16); + err_next[x + 1u] += (int16_t)((e * 5) / 16); + err_next[x + 2u] += (int16_t)(e / 16); + } + } + + if (use_dither) { + int16_t *tmp = err_curr; + err_curr = err_next; + err_next = tmp; + memset(err_next, 0, (RASTER_WIDTH + 2u) * sizeof(int16_t)); + } + } + + free(err_curr); + free(err_next); + free(x_map); + free(y_map); + free(luma); + + *out_width = dst_width; + *out_height = dst_height; + *out_raster = raster; + *out_len = len; + return ESP_OK; +} + +esp_err_t raster_tools_convert_png_to_raster_384(const uint8_t *png, + size_t png_len, + bool scale_to_width, + uint8_t threshold, + bool invert, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len) { + if (png == NULL || png_len == 0 || + out_width == NULL || out_height == NULL || out_raster == NULL || out_len == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + *out_width = 0; + *out_height = 0; + *out_raster = NULL; + *out_len = 0; + + if (png_len > UINT32_MAX) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "png too large"); + } + return ESP_ERR_INVALID_SIZE; + } + + if (max_height == 0 || max_height > 3000) { + max_height = 3000; + } + + png_image image; + memset(&image, 0, sizeof(image)); + image.version = PNG_IMAGE_VERSION; + + if (!png_image_begin_read_from_memory(&image, png, png_len) || + image.width == 0 || image.height == 0) { + png_image_free(&image); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid png"); + } + return ESP_FAIL; + } + + if (image.width > PNG_DECODE_MAX_WIDTH) { + png_image_free(&image); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "png too wide"); + } + return ESP_ERR_INVALID_SIZE; + } + + image.format = PNG_FORMAT_GRAY; + png_alloc_size_t gray_size = PNG_IMAGE_SIZE(image); + if (gray_size == 0 || gray_size > PNG_DECODE_MAX_BYTES) { + png_image_free(&image); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "png output too large"); + } + return ESP_ERR_INVALID_SIZE; + } + + if (image.width > UINT16_MAX || image.height > UINT16_MAX) { + png_image_free(&image); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "png dimensions too large"); + } + return ESP_ERR_INVALID_SIZE; + } + + uint8_t *gray = (uint8_t *)alloc_prefer_psram((size_t)gray_size); + if (gray == NULL) { + png_image_free(&image); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + png_alloc_size_t stride = PNG_IMAGE_ROW_STRIDE(image); + if (!png_image_finish_read(&image, NULL, gray, stride, NULL)) { + const char *png_err = image.message[0] != '\0' ? image.message : "png decode failed"; + png_image_free(&image); + free(gray); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", png_err); + } + return ESP_FAIL; + } + png_image_free(&image); + + esp_err_t convert_rc = raster_tools_convert_gray8_to_raster_384(gray, + (uint16_t)image.width, + (uint16_t)image.height, + scale_to_width, + threshold, + invert, + max_height, + out_width, + out_height, + out_raster, + out_len, + err, + err_len); + free(gray); + return convert_rc; +} + +static enum qrcodegen_Ecc map_qr_ecc(uint8_t ecc_level) { + switch (ecc_level) { + case 0: + return qrcodegen_Ecc_LOW; + case 1: + return qrcodegen_Ecc_MEDIUM; + case 2: + return qrcodegen_Ecc_QUARTILE; + case 3: + default: + return qrcodegen_Ecc_HIGH; + } +} + +esp_err_t raster_tools_render_qr_384(const char *text, + uint8_t module_scale, + uint8_t margin_modules, + uint8_t ecc_level, + uint16_t max_height, + uint16_t *out_width, + uint16_t *out_height, + uint8_t **out_raster, + size_t *out_len, + char *err, + size_t err_len) { + if (text == NULL || text[0] == '\0' || + out_width == NULL || out_height == NULL || out_raster == NULL || out_len == NULL) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "invalid args"); + } + return ESP_ERR_INVALID_ARG; + } + + if (max_height == 0 || max_height > 3000) { + max_height = 3000; + } + + if (margin_modules == 0) { + margin_modules = 2; + } + + size_t qr_buf_len = qrcodegen_BUFFER_LEN_MAX; + uint8_t *temp = (uint8_t *)malloc(qr_buf_len); + uint8_t *qr = (uint8_t *)malloc(qr_buf_len); + if (temp == NULL || qr == NULL) { + free(temp); + free(qr); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + bool ok = qrcodegen_encodeText(text, + temp, + qr, + map_qr_ecc(ecc_level), + qrcodegen_VERSION_MIN, + qrcodegen_VERSION_MAX, + qrcodegen_Mask_AUTO, + true); + if (!ok) { + free(temp); + free(qr); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "qr encode failed"); + } + return ESP_FAIL; + } + + int qr_size = qrcodegen_getSize(qr); + int full_modules = qr_size + 2 * margin_modules; + + if (module_scale == 0) { + module_scale = (uint8_t)(RASTER_WIDTH / full_modules); + if (module_scale == 0) { + module_scale = 1; + } + } + + uint32_t image_size = (uint32_t)full_modules * module_scale; + if (image_size > RASTER_WIDTH || image_size > max_height) { + free(temp); + free(qr); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "qr too large for 384 width"); + } + return ESP_ERR_INVALID_SIZE; + } + + uint16_t out_h = (uint16_t)image_size; + size_t len = (size_t)RASTER_BYTES_PER_ROW * out_h; + uint8_t *raster = (uint8_t *)calloc_prefer_psram(1, len); + if (raster == NULL) { + free(temp); + free(qr); + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "no memory"); + } + return ESP_ERR_NO_MEM; + } + + uint16_t x_origin = (uint16_t)((RASTER_WIDTH - image_size) / 2); + for (int my = 0; my < full_modules; ++my) { + for (int mx = 0; mx < full_modules; ++mx) { + int qx = mx - margin_modules; + int qy = my - margin_modules; + bool black = (qx >= 0 && qx < qr_size && qy >= 0 && qy < qr_size) + ? qrcodegen_getModule(qr, qx, qy) + : false; + if (!black) { + continue; + } + + uint16_t px0 = (uint16_t)(x_origin + mx * module_scale); + uint16_t py0 = (uint16_t)(my * module_scale); + for (uint8_t sy = 0; sy < module_scale; ++sy) { + uint16_t py = (uint16_t)(py0 + sy); + if (py >= out_h) { + continue; + } + for (uint8_t sx = 0; sx < module_scale; ++sx) { + uint16_t px = (uint16_t)(px0 + sx); + if (px < RASTER_WIDTH) { + set_black(raster, RASTER_WIDTH, px, py); + } + } + } + } + } + + free(temp); + free(qr); + + *out_width = RASTER_WIDTH; + *out_height = out_h; + *out_raster = raster; + *out_len = len; + return ESP_OK; +} diff --git a/components/domain/src/screen_preview.c b/components/domain/src/screen_preview.c new file mode 100644 index 0000000..961b3aa --- /dev/null +++ b/components/domain/src/screen_preview.c @@ -0,0 +1,22 @@ +#include "domain.h" +#include "platform.h" + +esp_err_t screen_preview_show_raster(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ + return platform_display_show_raster_1bpp(raster, raster_len, width, height, timeout_ms, err, err_len); +} + +esp_err_t screen_preview_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ + return platform_display_show_png(png, png_len, timeout_ms, err, err_len); +} diff --git a/components/domain/src/system_runtime.c b/components/domain/src/system_runtime.c new file mode 100644 index 0000000..ad3fd64 --- /dev/null +++ b/components/domain/src/system_runtime.c @@ -0,0 +1,34 @@ +#include "domain.h" +#include "platform.h" + +esp_err_t system_runtime_start(void) { + esp_err_t err = platform_bootstrap_init(); + if (err != ESP_OK) { + return err; + } + + err = wifi_manager_start(); + if (err != ESP_OK) { + // Reset platform state so lifecycle retry runs from a clean baseline. + (void)wifi_manager_stop(); + return err; + } + + return ESP_OK; +} + +esp_err_t system_runtime_shutdown(void) { + return wifi_manager_stop(); +} + +esp_err_t system_runtime_bootstrap(void) { + return system_runtime_start(); +} + +bool system_runtime_wifi_ready(void) { + return wifi_manager_is_ready(); +} + +void system_runtime_get_ip(char *buf, size_t buf_len) { + wifi_manager_get_ip(buf, buf_len); +} diff --git a/components/domain/src/voice_interaction.c b/components/domain/src/voice_interaction.c new file mode 100644 index 0000000..ff09f90 --- /dev/null +++ b/components/domain/src/voice_interaction.c @@ -0,0 +1,529 @@ +#include "voice_interaction_internal.h" + +#include +#include +#include + +#include "esp_crt_bundle.h" +#include "esp_log.h" + +static const char *TAG = "voice_interaction"; + +static uint32_t clamp_timeout_ms(uint32_t timeout_ms, uint32_t default_ms, uint32_t min_ms, uint32_t max_ms) { + uint32_t value = timeout_ms == 0 ? default_ms : timeout_ms; + if (value < min_ms) { + value = min_ms; + } + if (value > max_ms) { + value = max_ms; + } + return value; +} + +static bool voice_wait_worker_tasks_exit(uint32_t timeout_ms) { + int64_t deadline_ms = voice_now_ms() + (int64_t)timeout_ms; + while (voice_now_ms() < deadline_ms) { + bool uplink_alive = false; + bool heartbeat_alive = false; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + uplink_alive = (s_voice.uplink_task != NULL); + heartbeat_alive = (s_voice.heartbeat_task != NULL); + voice_unlock(); + } + + if (!uplink_alive && !heartbeat_alive) { + return true; + } + vTaskDelay(pdMS_TO_TICKS(20)); + } + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + ESP_LOGW(TAG, + "[stage] worker_task_exit_timeout: uplink_alive=%d heartbeat_alive=%d", + s_voice.uplink_task != NULL, + s_voice.heartbeat_task != NULL); + voice_unlock(); + } + return false; +} + +const char *voice_interaction_dialog_state_str(voice_dialog_state_t state) { + switch (state) { + case VOICE_DIALOG_STATE_IDLE: + return "Idle"; + case VOICE_DIALOG_STATE_LISTENING: + return "Listening"; + case VOICE_DIALOG_STATE_THINKING: + return "Thinking"; + case VOICE_DIALOG_STATE_RESPONDING: + return "Responding"; + default: + return "Unknown"; + } +} + +esp_err_t voice_interaction_init(void) { + if (s_voice.ready) { + return ESP_OK; + } + + memset(&s_voice, 0, sizeof(s_voice)); + + s_voice.lock = xSemaphoreCreateMutex(); + if (s_voice.lock == NULL) { + return ESP_ERR_NO_MEM; + } + + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.last_event_ms = voice_now_ms(); + s_voice.ready = true; + return ESP_OK; +} + +esp_err_t voice_interaction_start_with_timeout(uint32_t timeout_ms, char *err, size_t err_len) { + uint32_t connect_timeout_ms = + clamp_timeout_ms(timeout_ms, VOICE_START_CONNECT_TIMEOUT_MS, 1000, 30000); + ESP_LOGI(TAG, "[stage] session_start_enter"); + if (!s_voice.ready) { + voice_fill_err(err, err_len, "voice interaction not initialized"); + ESP_LOGW(TAG, "[stage] session_start_abort: not initialized"); + return ESP_ERR_INVALID_STATE; + } + + if (strlen(CONFIG_TQ_VOICE_API_KEY) == 0 || + strlen(CONFIG_TQ_VOICE_WORKSPACE_ID) == 0 || + strlen(CONFIG_TQ_VOICE_APP_ID) == 0) { + voice_fill_err(err, err_len, "voice API key/workspace/app_id is missing"); + ESP_LOGW(TAG, "[stage] session_start_abort: config missing"); + return ESP_ERR_INVALID_STATE; + } + ESP_LOGI(TAG, + "[stage] session_config_ok: ws_uri=%s sample_rate=%d frame_ms=%d bitrate_kbps=%d ws_stack=%d", + CONFIG_TQ_VOICE_WS_URI, + CONFIG_TQ_VOICE_SAMPLE_RATE, + CONFIG_TQ_VOICE_OPUS_FRAME_MS, + CONFIG_TQ_VOICE_OPUS_BITRATE_KBPS, + VOICE_WS_TASK_STACK); + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGW(TAG, "[stage] session_start_abort: lock timeout"); + return ESP_ERR_TIMEOUT; + } + bool already_active = s_voice.session_active; + bool ws_connected = s_voice.ws_connected; + bool started = s_voice.started; + voice_unlock(); + + if (already_active) { + if (ws_connected && started) { + ESP_LOGI(TAG, "[stage] session_start_skip: already active"); + voice_log_status_snapshot("already_active"); + return ESP_OK; + } + + ESP_LOGW(TAG, + "[stage] session_start_recover: active=%d ws_connected=%d started=%d", + already_active, + ws_connected, + started); + (void)voice_interaction_stop(NULL, 0); + } + + voice_interaction_ws_init_cjson_hooks(); + + ESP_LOGI(TAG, "[stage] opus_setup_begin"); + esp_err_t opus_setup_err = voice_setup_opus(err, err_len); + if (opus_setup_err != ESP_OK) { + ESP_LOGE(TAG, "voice opus setup failed: %s", esp_err_to_name(opus_setup_err)); + goto exit_err; + } + ESP_LOGI(TAG, "[stage] opus_setup_ok"); + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_make_uuid(s_voice.task_id); + voice_make_device_uuid(s_voice.device_uuid); + s_voice.dialog_id[0] = '\0'; + s_voice.last_error[0] = '\0'; + s_voice.upstream_packets = 0; + s_voice.downstream_packets = 0; + s_voice.last_downstream_ms = 0; + s_voice.playback_deadline_ms = 0; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.stop_requested = false; + s_voice.tap_active = false; + s_voice.ws_low_stack_warned = false; + s_voice.response_first_sentence_checked = false; + s_voice.uplink_task_with_caps = false; + s_voice.heartbeat_task_with_caps = false; + s_voice.last_event_ms = voice_now_ms(); + ESP_LOGI(TAG, + "[stage] session_context_prepared: task_id=%s device_uuid=%s", + s_voice.task_id, + s_voice.device_uuid); + voice_unlock(); + } + + esp_websocket_client_config_t ws_cfg = { + .uri = CONFIG_TQ_VOICE_WS_URI, + .task_name = "voice_ws", + .task_prio = 5, + .task_stack = VOICE_WS_TASK_STACK, + .buffer_size = 2048, + .network_timeout_ms = 10000, + .reconnect_timeout_ms = 3000, + .ping_interval_sec = 20, + .disable_auto_reconnect = false, + .pingpong_timeout_sec = 10, +#if CONFIG_MBEDTLS_CERTIFICATE_BUNDLE + .crt_bundle_attach = esp_crt_bundle_attach, +#endif + }; + + ESP_LOGI(TAG, "[stage] ws_init_begin"); + esp_websocket_client_handle_t ws = esp_websocket_client_init(&ws_cfg); + if (ws == NULL) { + voice_fill_err(err, err_len, "websocket init failed"); + ESP_LOGE(TAG, "[stage] ws_init_failed"); + goto exit_err; + } + ESP_LOGI(TAG, "[stage] ws_init_ok"); + + size_t auth_len = strlen(CONFIG_TQ_VOICE_API_KEY) + 8; + char *auth_value = (char *)voice_malloc_prefer_psram(auth_len); + if (auth_value == NULL) { + voice_fill_err(err, err_len, "no memory for auth header"); + ESP_LOGE(TAG, "[stage] ws_auth_header_alloc_failed"); + esp_websocket_client_destroy(ws); + goto exit_err; + } + snprintf(auth_value, auth_len, "Bearer %s", CONFIG_TQ_VOICE_API_KEY); + esp_websocket_client_append_header(ws, "Authorization", auth_value); + free(auth_value); + ESP_LOGI(TAG, "[stage] ws_auth_header_set"); + + ESP_LOGI(TAG, "[stage] ws_register_events_begin"); + esp_err_t reg_err = esp_websocket_register_events(ws, + WEBSOCKET_EVENT_ANY, + voice_websocket_event_handler, + NULL); + if (reg_err != ESP_OK) { + voice_fill_err(err, err_len, "websocket register events failed"); + ESP_LOGE(TAG, "[stage] ws_register_events_failed: %s", esp_err_to_name(reg_err)); + esp_websocket_client_destroy(ws); + goto exit_err; + } + ESP_LOGI(TAG, "[stage] ws_register_events_ok"); + + ESP_LOGI(TAG, "[stage] ws_start_begin"); + esp_err_t ws_start_err = esp_websocket_client_start(ws); + if (ws_start_err != ESP_OK) { + voice_fill_err(err, err_len, "websocket start failed"); + ESP_LOGE(TAG, "[stage] ws_start_failed: %s", esp_err_to_name(ws_start_err)); + esp_websocket_client_destroy(ws); + goto exit_err; + } + ESP_LOGI(TAG, "[stage] ws_start_ok"); + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGE(TAG, "[stage] session_start_abort: lock timeout after ws_start"); + esp_websocket_client_stop(ws); + esp_websocket_client_destroy(ws); + goto exit_err; + } + s_voice.ws = ws; + s_voice.session_active = true; + s_voice.ws_connected = false; + s_voice.started = false; + voice_unlock(); + voice_log_status_snapshot("session_marked_active"); + voice_log_heap_snapshot("before_create_uplink"); + + ESP_LOGI(TAG, "[stage] uplink_task_create_begin"); + BaseType_t ok = voice_create_task_prefer_psram(voice_uplink_task, + "voice_uplink", + VOICE_UPLINK_TASK_STACK, + 5, + &s_voice.uplink_task, + &s_voice.uplink_task_with_caps); + if (ok != pdPASS) { + voice_fill_err(err, err_len, "create uplink task failed"); + ESP_LOGE(TAG, "[stage] uplink_task_create_failed"); + voice_log_heap_snapshot("uplink_create_failed"); + (void)voice_interaction_stop(NULL, 0); + return ESP_ERR_NO_MEM; + } + ESP_LOGI(TAG, "[stage] uplink_task_create_ok"); + voice_log_heap_snapshot("after_create_uplink"); + + ESP_LOGI(TAG, "[stage] heartbeat_task_create_begin"); + ok = voice_create_task_prefer_psram(voice_heartbeat_task, + "voice_hb", + VOICE_HEARTBEAT_TASK_STACK, + 4, + &s_voice.heartbeat_task, + &s_voice.heartbeat_task_with_caps); + if (ok != pdPASS) { + voice_fill_err(err, err_len, "create heartbeat task failed"); + ESP_LOGE(TAG, "[stage] heartbeat_task_create_failed"); + voice_log_heap_snapshot("heartbeat_create_failed"); + (void)voice_interaction_stop(NULL, 0); + return ESP_ERR_NO_MEM; + } + ESP_LOGI(TAG, "[stage] heartbeat_task_create_ok"); + voice_log_heap_snapshot("after_create_heartbeat"); + + ESP_LOGI(TAG, "[stage] wait_ws_connected_begin: timeout_ms=%u", (unsigned)connect_timeout_ms); + int64_t deadline = voice_now_ms() + connect_timeout_ms; + while (voice_now_ms() < deadline) { + bool connected = false; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + connected = s_voice.ws_connected; + voice_unlock(); + } + if (connected) { + break; + } + vTaskDelay(pdMS_TO_TICKS(100)); + } + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGE(TAG, "[stage] wait_ws_connected_abort: lock timeout"); + (void)voice_interaction_stop(NULL, 0); + return ESP_ERR_TIMEOUT; + } + bool connected = s_voice.ws_connected; + voice_unlock(); + if (!connected) { + voice_fill_err(err, err_len, "websocket connect timeout"); + ESP_LOGE(TAG, "[stage] wait_ws_connected_timeout"); + voice_log_status_snapshot("wait_ws_connected_timeout"); + (void)voice_interaction_stop(NULL, 0); + return ESP_ERR_TIMEOUT; + } + + ESP_LOGI(TAG, "[stage] wait_ws_connected_ok"); + voice_log_status_snapshot("session_start_exit_ok"); + return ESP_OK; + +exit_err: + ESP_LOGE(TAG, "[stage] session_start_exit_err: %s", (err != NULL && err[0] != '\0') ? err : "unknown"); + voice_release_runtime_resources(); + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_MS, "session_start_exit_err_close"); + return ESP_FAIL; +} + +esp_err_t voice_interaction_start(char *err, size_t err_len) { + return voice_interaction_start_with_timeout(VOICE_START_CONNECT_TIMEOUT_MS, err, err_len); +} + +esp_err_t voice_interaction_stop_with_timeout(uint32_t timeout_ms, char *err, size_t err_len) { + uint32_t worker_exit_timeout_ms = clamp_timeout_ms(timeout_ms, 1500, 500, 10000); + ESP_LOGI(TAG, "[stage] session_stop_enter"); + + if (!s_voice.ready) { + voice_fill_err(err, err_len, "voice interaction not initialized"); + ESP_LOGW(TAG, "[stage] session_stop_abort: not initialized"); + return ESP_ERR_INVALID_STATE; + } + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGW(TAG, "[stage] session_stop_abort: lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_voice.session_active) { + voice_unlock(); + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_MS, "session_stop_skip_close"); + ESP_LOGI(TAG, "[stage] session_stop_skip: not active"); + return ESP_OK; + } + + s_voice.stop_requested = true; + bool ws_connected = s_voice.ws_connected; + TaskHandle_t uplink_task = s_voice.uplink_task; + TaskHandle_t heartbeat_task = s_voice.heartbeat_task; + esp_websocket_client_handle_t ws = s_voice.ws; + + s_voice.tap_active = false; + voice_unlock(); + voice_log_status_snapshot("session_stop_requested"); + + if (ws_connected) { + (void)voice_send_directive("finish-task", "Stop", true); + } + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_ON_STOP_MS, "session_stop_close"); + if (uplink_task != NULL) { + (void)xTaskAbortDelay(uplink_task); + } + if (heartbeat_task != NULL) { + (void)xTaskAbortDelay(heartbeat_task); + } + bool workers_exited = voice_wait_worker_tasks_exit(worker_exit_timeout_ms); + if (!workers_exited) { + voice_fill_err(err, err_len, "voice worker exit timeout"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_set_last_error_locked("worker exit timeout"); + voice_unlock(); + } + ESP_LOGW(TAG, "[stage] session_stop_abort: workers still alive"); + return ESP_ERR_TIMEOUT; + } + + if (ws != NULL) { + ESP_LOGI(TAG, "[stage] ws_stop_destroy_begin"); + esp_websocket_unregister_events(ws, + WEBSOCKET_EVENT_ANY, + voice_websocket_event_handler); + esp_websocket_client_stop(ws); + esp_websocket_client_destroy(ws); + ESP_LOGI(TAG, "[stage] ws_stop_destroy_ok"); + } + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.ws = NULL; + s_voice.uplink_task = NULL; + s_voice.heartbeat_task = NULL; + s_voice.uplink_task_with_caps = false; + s_voice.heartbeat_task_with_caps = false; + s_voice.ws_connected = false; + s_voice.started = false; + s_voice.session_active = false; + s_voice.stop_requested = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.dialog_id[0] = '\0'; + s_voice.response_first_sentence_checked = false; + s_voice.last_downstream_ms = 0; + s_voice.playback_deadline_ms = 0; + voice_unlock(); + } + voice_log_status_snapshot("session_stop_cleared"); + + voice_release_runtime_resources(); + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_MS, "session_stop_exit_close"); + ESP_LOGI(TAG, "[stage] session_stop_exit_ok"); + return ESP_OK; +} + +esp_err_t voice_interaction_stop(char *err, size_t err_len) { + return voice_interaction_stop_with_timeout(1500, err, err_len); +} + +esp_err_t voice_interaction_tap_start(char *err, size_t err_len) { + ESP_LOGI(TAG, "[stage] tap_start_enter"); + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGW(TAG, "[stage] tap_start_abort: lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_voice.session_active || !s_voice.ws_connected || !s_voice.started) { + ESP_LOGW(TAG, + "[stage] tap_start_abort: session_active=%d ws_connected=%d started=%d", + s_voice.session_active, + s_voice.ws_connected, + s_voice.started); + voice_unlock(); + voice_fill_err(err, err_len, "voice session not ready"); + return ESP_ERR_INVALID_STATE; + } + + voice_unlock(); + voice_log_heap_snapshot("tap_start_before_audio_open"); + + esp_err_t audio_err = voice_open_audio_for_dialog(err, err_len); + if (audio_err != ESP_OK) { + voice_log_heap_snapshot("tap_start_audio_open_failed"); + return audio_err; + } + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + voice_audio_close(); + ESP_LOGW(TAG, "[stage] tap_start_abort: lock timeout after audio open"); + return ESP_ERR_TIMEOUT; + } + + if (!s_voice.session_active || !s_voice.ws_connected || !s_voice.started) { + ESP_LOGW(TAG, + "[stage] tap_start_abort_after_audio_open: session_active=%d ws_connected=%d started=%d", + s_voice.session_active, + s_voice.ws_connected, + s_voice.started); + voice_unlock(); + voice_audio_close(); + voice_fill_err(err, err_len, "voice session not ready"); + return ESP_ERR_INVALID_STATE; + } + + bool listening = (s_voice.dialog_state == VOICE_DIALOG_STATE_LISTENING); + s_voice.tap_active = true; + voice_unlock(); + ESP_LOGI(TAG, "[stage] tap_start_marked_active: listening=%d", listening); + + if (!listening) { + (void)voice_send_directive("continue-task", "RequestToSpeak", true); + } + + voice_log_status_snapshot("tap_start_exit_ok"); + return ESP_OK; +} + +esp_err_t voice_interaction_tap_cancel(char *err, size_t err_len) { + ESP_LOGI(TAG, "[stage] tap_cancel_enter"); + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_fill_err(err, err_len, "voice lock timeout"); + ESP_LOGW(TAG, "[stage] tap_cancel_abort: lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_voice.session_active || !s_voice.ws_connected || !s_voice.started) { + ESP_LOGW(TAG, + "[stage] tap_cancel_abort: session_active=%d ws_connected=%d started=%d", + s_voice.session_active, + s_voice.ws_connected, + s_voice.started); + voice_unlock(); + voice_fill_err(err, err_len, "voice session not ready"); + return ESP_ERR_INVALID_STATE; + } + + s_voice.tap_active = false; + voice_unlock(); + voice_log_status_snapshot("tap_cancel_marked_inactive"); + esp_err_t cancel_err = voice_send_directive("continue-task", "CancelSpeech", true); + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_ON_STOP_MS, "tap_cancel_close"); + return cancel_err; +} + +void voice_interaction_get_status(voice_interaction_status_t *out_status) { + if (out_status == NULL) { + return; + } + + memset(out_status, 0, sizeof(*out_status)); + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + return; + } + + out_status->ready = s_voice.ready; + out_status->session_active = s_voice.session_active; + out_status->ws_connected = s_voice.ws_connected; + out_status->started = s_voice.started; + out_status->tap_active = s_voice.tap_active; + out_status->marker_image_gen_running = voice_marker_image_generation_is_running(); + out_status->dialog_state = s_voice.dialog_state; + out_status->last_event_ms = s_voice.last_event_ms; + out_status->upstream_packets = s_voice.upstream_packets; + out_status->downstream_packets = s_voice.downstream_packets; + + strlcpy(out_status->task_id, s_voice.task_id, sizeof(out_status->task_id)); + strlcpy(out_status->dialog_id, s_voice.dialog_id, sizeof(out_status->dialog_id)); + strlcpy(out_status->last_error, s_voice.last_error, sizeof(out_status->last_error)); + + voice_unlock(); +} diff --git a/components/domain/src/voice_interaction_common.c b/components/domain/src/voice_interaction_common.c new file mode 100644 index 0000000..4d6eced --- /dev/null +++ b/components/domain/src/voice_interaction_common.c @@ -0,0 +1,488 @@ +#include "voice_interaction_internal.h" + +#include +#include +#include +#include + +#include "esp_audio_dec.h" +#include "esp_audio_enc.h" +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "esp_mac.h" +#include "esp_random.h" +#include "esp_system.h" +#include "esp_timer.h" +#include "freertos/idf_additions.h" + +static const char *TAG = "voice_interaction"; + +voice_context_t s_voice; + +int64_t voice_now_ms(void) { + return esp_timer_get_time() / 1000; +} + +void voice_fill_err(char *err, size_t err_len, const char *msg) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", (msg != NULL) ? msg : "unknown error"); + } +} + +void voice_set_last_error_locked(const char *msg) { + if (msg == NULL) { + s_voice.last_error[0] = '\0'; + return; + } + strlcpy(s_voice.last_error, msg, sizeof(s_voice.last_error)); +} + +bool voice_lock(uint32_t timeout_ms) { + return s_voice.lock != NULL && xSemaphoreTake(s_voice.lock, pdMS_TO_TICKS(timeout_ms)) == pdTRUE; +} + +void voice_unlock(void) { + if (s_voice.lock != NULL) { + xSemaphoreGive(s_voice.lock); + } +} + +void voice_log_status_snapshot(const char *stage) { + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + ESP_LOGW(TAG, "[stage] %s: status snapshot lock timeout", stage); + return; + } + + ESP_LOGI(TAG, + "[stage] %s: active=%d ws=%d started=%d tap=%d state=%s up=%" PRIu32 " down=%" PRIu32 " err=%s", + stage, + s_voice.session_active, + s_voice.ws_connected, + s_voice.started, + s_voice.tap_active, + voice_interaction_dialog_state_str(s_voice.dialog_state), + s_voice.upstream_packets, + s_voice.downstream_packets, + s_voice.last_error[0] != '\0' ? s_voice.last_error : "-"); + voice_unlock(); +} + +void voice_log_heap_snapshot(const char *stage) { + size_t free_8bit = heap_caps_get_free_size(MALLOC_CAP_8BIT); + size_t free_internal = heap_caps_get_free_size(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT); + size_t free_dma = heap_caps_get_free_size(MALLOC_CAP_DMA | MALLOC_CAP_8BIT); + size_t free_spiram = heap_caps_get_free_size(MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + size_t largest_8bit = heap_caps_get_largest_free_block(MALLOC_CAP_8BIT); + size_t largest_internal = heap_caps_get_largest_free_block(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT); + size_t largest_dma = heap_caps_get_largest_free_block(MALLOC_CAP_DMA | MALLOC_CAP_8BIT); + size_t largest_spiram = heap_caps_get_largest_free_block(MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + ESP_LOGI(TAG, + "[stage] %s heap: free8=%u free_internal=%u free_dma=%u free_spiram=%u largest8=%u largest_internal=%u largest_dma=%u largest_spiram=%u", + stage, + (unsigned)free_8bit, + (unsigned)free_internal, + (unsigned)free_dma, + (unsigned)free_spiram, + (unsigned)largest_8bit, + (unsigned)largest_internal, + (unsigned)largest_dma, + (unsigned)largest_spiram); +} + +void voice_wait_audio_playback_done(uint32_t timeout_ms, const char *stage) { + if (!voice_audio_is_open() || timeout_ms == 0) { + return; + } + + int64_t deadline_ms = voice_now_ms() + (int64_t)timeout_ms; + while (voice_now_ms() < deadline_ms) { + int64_t playback_deadline_ms = 0; + int64_t last_downstream_ms = 0; + voice_dialog_state_t dialog_state = VOICE_DIALOG_STATE_IDLE; + bool ws_connected = false; + bool started = false; + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + break; + } + playback_deadline_ms = s_voice.playback_deadline_ms; + last_downstream_ms = s_voice.last_downstream_ms; + dialog_state = s_voice.dialog_state; + ws_connected = s_voice.ws_connected; + started = s_voice.started; + voice_unlock(); + + int64_t now_ms = voice_now_ms(); + bool codec_tail_done = now_ms >= playback_deadline_ms; + bool downstream_quiet = (last_downstream_ms == 0) || + ((now_ms - last_downstream_ms) >= VOICE_AUDIO_DRAIN_QUIET_MS); + bool remote_not_responding = !ws_connected || + !started || + dialog_state != VOICE_DIALOG_STATE_RESPONDING; + if (codec_tail_done && downstream_quiet && remote_not_responding) { + ESP_LOGI(TAG, + "[stage] %s: audio_drain_done now=%" PRId64 " play_deadline=%" PRId64 " last_down=%" PRId64, + stage != NULL ? stage : "audio_drain", + now_ms, + playback_deadline_ms, + last_downstream_ms); + return; + } + + vTaskDelay(pdMS_TO_TICKS(30)); + } + + ESP_LOGI(TAG, + "[stage] %s: audio_drain_timeout timeout_ms=%u", + stage != NULL ? stage : "audio_drain", + (unsigned)timeout_ms); +} + +void voice_close_audio_with_drain(uint32_t timeout_ms, const char *stage) { + if (!voice_audio_is_open()) { + return; + } + + voice_wait_audio_playback_done(timeout_ms, stage); + voice_audio_close(); + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.last_downstream_ms = 0; + s_voice.playback_deadline_ms = 0; + voice_unlock(); + } +} + +void *voice_malloc_prefer_psram(size_t size) { + void *ptr = heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = malloc(size); + } + return ptr; +} + +void *voice_calloc_prefer_psram(size_t n, size_t size) { + void *ptr = heap_caps_calloc(n, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = calloc(n, size); + } + return ptr; +} + +void *voice_realloc_prefer_psram(void *ptr, size_t size) { + void *new_ptr = heap_caps_realloc(ptr, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (new_ptr == NULL) { + new_ptr = realloc(ptr, size); + } + return new_ptr; +} + +BaseType_t voice_create_task_prefer_psram(TaskFunction_t task_fn, + const char *name, + uint32_t stack_size, + UBaseType_t priority, + TaskHandle_t *out_task, + bool *out_with_caps) { + if (out_with_caps != NULL) { + *out_with_caps = false; + } + + BaseType_t rc = pdFAIL; + +#if defined(CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY) && \ + defined(CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM) && \ + (configSUPPORT_STATIC_ALLOCATION == 1) + rc = xTaskCreatePinnedToCoreWithCaps(task_fn, + name, + (configSTACK_DEPTH_TYPE)stack_size, + NULL, + priority, + out_task, + tskNO_AFFINITY, + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (rc == pdPASS) { + if (out_with_caps != NULL) { + *out_with_caps = true; + } + ESP_LOGI(TAG, "[stage] task_create_psram_ok: name=%s stack=%u", name, (unsigned)stack_size); + return pdPASS; + } + ESP_LOGW(TAG, "[stage] task_create_psram_failed: name=%s stack=%u", name, (unsigned)stack_size); +#endif + + rc = xTaskCreate(task_fn, + name, + (configSTACK_DEPTH_TYPE)stack_size, + NULL, + priority, + out_task); + if (rc == pdPASS) { + ESP_LOGI(TAG, "[stage] task_create_internal_ok: name=%s stack=%u", name, (unsigned)stack_size); + } else { + ESP_LOGE(TAG, "[stage] task_create_internal_failed: name=%s stack=%u", name, (unsigned)stack_size); + } + return rc; +} + +void voice_delete_task(TaskHandle_t task, bool with_caps) { + if (task == NULL) { + return; + } + +#if (configSUPPORT_STATIC_ALLOCATION == 1) + if (with_caps) { + vTaskDeleteWithCaps(task); + return; + } +#else + (void)with_caps; +#endif + vTaskDelete(task); +} + +void voice_delete_self_task(bool with_caps) { +#if (configSUPPORT_STATIC_ALLOCATION == 1) + if (with_caps) { + vTaskDeleteWithCaps(NULL); + return; + } +#else + (void)with_caps; +#endif + vTaskDelete(NULL); +} + +void voice_make_uuid(char out[40]) { + uint8_t raw[16]; + esp_fill_random(raw, sizeof(raw)); + + raw[6] = (uint8_t)((raw[6] & 0x0F) | 0x40); + raw[8] = (uint8_t)((raw[8] & 0x3F) | 0x80); + + snprintf(out, + 40, + "%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-%02x%02x%02x%02x%02x%02x", + raw[0], + raw[1], + raw[2], + raw[3], + raw[4], + raw[5], + raw[6], + raw[7], + raw[8], + raw[9], + raw[10], + raw[11], + raw[12], + raw[13], + raw[14], + raw[15]); +} + +void voice_make_device_uuid(char out[40]) { + if (strlen(CONFIG_TQ_VOICE_DEVICE_UUID) > 0) { + strlcpy(out, CONFIG_TQ_VOICE_DEVICE_UUID, 40); + return; + } + + uint8_t mac[6] = {0}; + esp_read_mac(mac, ESP_MAC_WIFI_STA); + + uint32_t r = esp_random(); + snprintf(out, + 40, + "%02x%02x%02x%02x-%02x%02x-4%03x-%04x-%012" PRIx32, + mac[0], + mac[1], + mac[2], + mac[3], + mac[4], + mac[5], + (unsigned)(r & 0x0FFF), + (unsigned)((r >> 12) & 0xFFFF), + esp_random()); +} + +const char *voice_safe_user_id(void) { + if (strlen(CONFIG_TQ_VOICE_USER_ID) > 0) { + return CONFIG_TQ_VOICE_USER_ID; + } + return "esp32-user"; +} + +static esp_opus_enc_frame_duration_t voice_to_enc_frame_duration(int frame_ms) { + switch (frame_ms) { + case 10: + return ESP_OPUS_ENC_FRAME_DURATION_10_MS; + case 20: + return ESP_OPUS_ENC_FRAME_DURATION_20_MS; + case 40: + return ESP_OPUS_ENC_FRAME_DURATION_40_MS; + case 60: + return ESP_OPUS_ENC_FRAME_DURATION_60_MS; + case 80: + return ESP_OPUS_ENC_FRAME_DURATION_80_MS; + case 100: + return ESP_OPUS_ENC_FRAME_DURATION_100_MS; + case 120: + return ESP_OPUS_ENC_FRAME_DURATION_120_MS; + default: + return ESP_OPUS_ENC_FRAME_DURATION_ARG; + } +} + +static esp_opus_dec_frame_duration_t voice_to_dec_frame_duration(int frame_ms) { + switch (frame_ms) { + case 10: + return ESP_OPUS_DEC_FRAME_DURATION_10_MS; + case 20: + return ESP_OPUS_DEC_FRAME_DURATION_20_MS; + case 40: + return ESP_OPUS_DEC_FRAME_DURATION_40_MS; + case 60: + return ESP_OPUS_DEC_FRAME_DURATION_60_MS; + case 80: + return ESP_OPUS_DEC_FRAME_DURATION_80_MS; + case 100: + return ESP_OPUS_DEC_FRAME_DURATION_100_MS; + case 120: + return ESP_OPUS_DEC_FRAME_DURATION_120_MS; + default: + return ESP_OPUS_DEC_FRAME_DURATION_INVALID; + } +} + +esp_err_t voice_setup_opus(char *err, size_t err_len) { + esp_opus_enc_frame_duration_t enc_duration = + voice_to_enc_frame_duration(CONFIG_TQ_VOICE_OPUS_FRAME_MS); + esp_opus_dec_frame_duration_t dec_duration = + voice_to_dec_frame_duration(CONFIG_TQ_VOICE_OPUS_FRAME_MS); + + if (enc_duration == ESP_OPUS_ENC_FRAME_DURATION_ARG || + dec_duration == ESP_OPUS_DEC_FRAME_DURATION_INVALID) { + voice_fill_err(err, err_len, "invalid opus frame duration"); + return ESP_ERR_INVALID_ARG; + } + + esp_opus_enc_config_t enc_cfg = ESP_OPUS_ENC_CONFIG_DEFAULT(); + enc_cfg.sample_rate = CONFIG_TQ_VOICE_SAMPLE_RATE; + enc_cfg.channel = ESP_AUDIO_MONO; + enc_cfg.bits_per_sample = ESP_AUDIO_BIT16; + enc_cfg.frame_duration = enc_duration; + enc_cfg.bitrate = CONFIG_TQ_VOICE_OPUS_BITRATE_KBPS * 1000; + enc_cfg.application_mode = ESP_OPUS_ENC_APPLICATION_VOIP; + enc_cfg.enable_vbr = true; + + esp_audio_err_t enc_err = esp_opus_enc_open(&enc_cfg, + sizeof(enc_cfg), + &s_voice.opus_enc); + if (enc_err != ESP_AUDIO_ERR_OK || s_voice.opus_enc == NULL) { + voice_fill_err(err, err_len, "opus encoder open failed"); + return ESP_FAIL; + } + + enc_err = esp_opus_enc_get_frame_size(s_voice.opus_enc, + &s_voice.opus_enc_in_size, + &s_voice.opus_enc_out_size); + if (enc_err != ESP_AUDIO_ERR_OK || + s_voice.opus_enc_in_size <= 0 || + s_voice.opus_enc_out_size <= 0) { + voice_fill_err(err, err_len, "opus frame size query failed"); + return ESP_FAIL; + } + + s_voice.pcm_tx_buf = (int16_t *)voice_malloc_prefer_psram((size_t)s_voice.opus_enc_in_size); + s_voice.opus_tx_buf = (uint8_t *)voice_malloc_prefer_psram((size_t)s_voice.opus_enc_out_size); + if (s_voice.pcm_tx_buf == NULL || s_voice.opus_tx_buf == NULL) { + voice_fill_err(err, err_len, "no memory for opus tx buffers"); + return ESP_ERR_NO_MEM; + } + + esp_opus_dec_cfg_t dec_cfg = ESP_OPUS_DEC_CONFIG_DEFAULT(); + dec_cfg.sample_rate = CONFIG_TQ_VOICE_SAMPLE_RATE; + dec_cfg.channel = ESP_AUDIO_MONO; + dec_cfg.frame_duration = dec_duration; + dec_cfg.self_delimited = false; + + esp_audio_err_t dec_err = esp_opus_dec_open(&dec_cfg, + sizeof(dec_cfg), + &s_voice.opus_dec); + if (dec_err != ESP_AUDIO_ERR_OK || s_voice.opus_dec == NULL) { + voice_fill_err(err, err_len, "opus decoder open failed"); + return ESP_FAIL; + } + + size_t rx_pcm_size = (size_t)CONFIG_TQ_VOICE_SAMPLE_RATE * + VOICE_SAMPLE_BYTES * + (size_t)CONFIG_TQ_VOICE_OPUS_FRAME_MS * + 2 / 1000; + if (rx_pcm_size < 2048) { + rx_pcm_size = 2048; + } + + s_voice.pcm_rx_buf = (uint8_t *)voice_malloc_prefer_psram(rx_pcm_size); + if (s_voice.pcm_rx_buf == NULL) { + voice_fill_err(err, err_len, "no memory for opus rx buffer"); + return ESP_ERR_NO_MEM; + } + s_voice.pcm_rx_buf_size = rx_pcm_size; + + return ESP_OK; +} + +esp_err_t voice_open_audio_for_dialog(char *err, size_t err_len) { + if (voice_audio_is_open()) { + return ESP_OK; + } + + voice_audio_open_config_t audio_cfg = { + .sample_rate = CONFIG_TQ_VOICE_SAMPLE_RATE, + .channels = 1, + .bits_per_sample = 16, + .output_volume = CONFIG_TQ_VOICE_CODEC_OUT_VOL, + .input_gain_db = (float)CONFIG_TQ_VOICE_CODEC_MIC_GAIN_DB, + }; + + ESP_LOGI(TAG, "[stage] audio_open_begin"); + esp_err_t open_err = voice_audio_open(&audio_cfg, err, err_len); + if (open_err != ESP_OK) { + ESP_LOGE(TAG, "[stage] audio_open_failed: %s", esp_err_to_name(open_err)); + return open_err; + } + + ESP_LOGI(TAG, "[stage] audio_open_ok"); + return ESP_OK; +} + +void voice_release_runtime_resources(void) { + if (s_voice.opus_enc != NULL) { + esp_opus_enc_close(s_voice.opus_enc); + s_voice.opus_enc = NULL; + } + if (s_voice.opus_dec != NULL) { + (void)esp_opus_dec_close(s_voice.opus_dec); + s_voice.opus_dec = NULL; + } + + free(s_voice.pcm_tx_buf); + s_voice.pcm_tx_buf = NULL; + + free(s_voice.opus_tx_buf); + s_voice.opus_tx_buf = NULL; + + free(s_voice.pcm_rx_buf); + s_voice.pcm_rx_buf = NULL; + s_voice.pcm_rx_buf_size = 0; + + free(s_voice.text_agg); + s_voice.text_agg = NULL; + s_voice.text_agg_size = 0; + + free(s_voice.bin_agg); + s_voice.bin_agg = NULL; + s_voice.bin_agg_size = 0; + + s_voice.opus_enc_in_size = 0; + s_voice.opus_enc_out_size = 0; +} diff --git a/components/domain/src/voice_interaction_marker.c b/components/domain/src/voice_interaction_marker.c new file mode 100644 index 0000000..7720256 --- /dev/null +++ b/components/domain/src/voice_interaction_marker.c @@ -0,0 +1,520 @@ +#include "voice_interaction_internal.h" + +#include +#include +#include +#include + +#include "esp_log.h" +#include "domain.h" + +static const char *TAG = "voice_interaction"; + +#define VOICE_IMAGE_MARKER_PROMPT_MAX_LEN 800 +#define VOICE_IMAGE_MARKER_FIRST_SENTENCE_MAX_LEN 1024 +#define VOICE_IMAGE_GEN_TASK_STACK 16384 +#define VOICE_IMAGE_GEN_TASK_PRIO 3 +#define VOICE_IMAGE_MARKER_REPEAT_SUPPRESS_MS 45000 +#define VOICE_IMAGE_PRINT_THRESHOLD 160 +#define VOICE_IMAGE_PRINT_MAX_HEIGHT 2200 +#define VOICE_IMAGE_PREVIEW_TIMEOUT_MS 200 +#define VOICE_IMAGE_MARKER_TEMPLATE \ + "%s,线稿风格,白色背景,边缘清晰,细节简洁,高对比,避免大面积阴影和灰度渐变,适配热敏打印机打印。" +#define VOICE_IMAGE_MARKER_TEMPLATE_FALLBACK_SUBJECT "简洁卡通图案" + +typedef struct { + char prompt[VOICE_IMAGE_MARKER_PROMPT_MAX_LEN + 1]; + char dialog_id[40]; +} voice_image_generation_task_arg_t; + +static portMUX_TYPE s_marker_image_gen_lock = portMUX_INITIALIZER_UNLOCKED; +static bool s_marker_image_gen_running; +static int64_t s_marker_last_success_ms; +static char s_marker_last_success_prompt[VOICE_IMAGE_MARKER_PROMPT_MAX_LEN + 1]; +static char s_marker_last_success_dialog_id[40]; + +static bool voice_marker_image_generation_try_acquire(const char *prompt, + const char *dialog_id, + int64_t now_ms, + uint32_t *out_remain_ms) { + bool acquired = false; + uint32_t remain_ms = 0; + const char *safe_prompt = prompt != NULL ? prompt : ""; + const char *safe_dialog = dialog_id != NULL ? dialog_id : ""; + + portENTER_CRITICAL(&s_marker_image_gen_lock); + if (s_marker_image_gen_running) { + acquired = false; + } else if (s_marker_last_success_ms > 0 && + strcmp(safe_prompt, s_marker_last_success_prompt) == 0 && + strcmp(safe_dialog, s_marker_last_success_dialog_id) == 0) { + int64_t elapsed_ms = now_ms - s_marker_last_success_ms; + if (elapsed_ms >= 0 && elapsed_ms < VOICE_IMAGE_MARKER_REPEAT_SUPPRESS_MS) { + remain_ms = (uint32_t)(VOICE_IMAGE_MARKER_REPEAT_SUPPRESS_MS - elapsed_ms); + acquired = false; + } else { + s_marker_image_gen_running = true; + acquired = true; + } + } else { + s_marker_image_gen_running = true; + acquired = true; + } + portEXIT_CRITICAL(&s_marker_image_gen_lock); + + if (out_remain_ms != NULL) { + *out_remain_ms = remain_ms; + } + return acquired; +} + +static void voice_marker_image_generation_release(void) { + portENTER_CRITICAL(&s_marker_image_gen_lock); + s_marker_image_gen_running = false; + portEXIT_CRITICAL(&s_marker_image_gen_lock); +} + +static void voice_marker_image_generation_record_success(const char *prompt, + const char *dialog_id, + int64_t now_ms) { + const char *safe_prompt = prompt != NULL ? prompt : ""; + const char *safe_dialog = dialog_id != NULL ? dialog_id : ""; + + portENTER_CRITICAL(&s_marker_image_gen_lock); + strlcpy(s_marker_last_success_prompt, safe_prompt, sizeof(s_marker_last_success_prompt)); + strlcpy(s_marker_last_success_dialog_id, safe_dialog, sizeof(s_marker_last_success_dialog_id)); + s_marker_last_success_ms = now_ms; + portEXIT_CRITICAL(&s_marker_image_gen_lock); +} + +static void voice_log_text_preview(const char *stage, const char *text) { + if (stage == NULL || text == NULL || text[0] == '\0') { + return; + } + + size_t len = strlen(text); + const int preview = 240; + ESP_LOGI(TAG, + "[stage] %s: len=%u text=%.*s%s", + stage, + (unsigned)len, + preview, + text, + (len > (size_t)preview) ? "..." : ""); +} + +static bool voice_is_space_char(char c) { + return isspace((unsigned char)c) != 0; +} + +static size_t voice_find_first_sentence_end(const char *text, size_t len) { + if (text == NULL || len == 0) { + return 0; + } + + for (size_t i = 0; i < len; ++i) { + unsigned char c = (unsigned char)text[i]; + if (c == '.' || c == '!' || c == '?' || c == '\n' || c == '\r') { + return i + 1; + } + + if (i + 2 < len) { + unsigned char b1 = (unsigned char)text[i]; + unsigned char b2 = (unsigned char)text[i + 1]; + unsigned char b3 = (unsigned char)text[i + 2]; + + if (b1 == 0xE3 && b2 == 0x80 && b3 == 0x82) { + return i + 3; + } + if (b1 == 0xEF && b2 == 0xBC && + (b3 == 0x81 || b3 == 0x9F || b3 == 0x9B)) { + return i + 3; + } + } + } + + return len; +} + +static bool voice_extract_first_sentence_text(const char *text, + char *out_sentence, + size_t out_len) { + if (text == NULL || out_sentence == NULL || out_len == 0) { + return false; + } + + size_t len = strlen(text); + size_t begin = 0; + while (begin < len && voice_is_space_char(text[begin])) { + begin++; + } + if (begin >= len) { + return false; + } + + size_t end = begin + voice_find_first_sentence_end(text + begin, len - begin); + while (end > begin && voice_is_space_char(text[end - 1])) { + end--; + } + if (end <= begin) { + return false; + } + + size_t copy_len = end - begin; + if (copy_len >= out_len) { + copy_len = out_len - 1; + } + memcpy(out_sentence, text + begin, copy_len); + out_sentence[copy_len] = '\0'; + return copy_len > 0; +} + +static bool voice_extract_marker_prompt(const char *text, char *out_prompt, size_t out_len) { + if (text == NULL || out_prompt == NULL || out_len == 0) { + return false; + } + + const char *open = strstr(text, "/*"); + if (open == NULL) { + return false; + } + + const char *close = strstr(open + 2, "*/"); + if (close == NULL) { + return false; + } + + const char *begin = open + 2; + const char *end = close; + while (begin < end && voice_is_space_char(*begin)) { + begin++; + } + while (end > begin && voice_is_space_char(*(end - 1))) { + end--; + } + if (end <= begin) { + return false; + } + + size_t prompt_len = (size_t)(end - begin); + if (prompt_len >= out_len) { + prompt_len = out_len - 1; + } + memcpy(out_prompt, begin, prompt_len); + out_prompt[prompt_len] = '\0'; + return prompt_len > 0; +} + +static void voice_build_marker_image_prompt(const char *subject, + char *out_prompt, + size_t out_len) { + if (out_prompt == NULL || out_len == 0) { + return; + } + + const char *safe_subject = (subject != NULL && subject[0] != '\0') ? + subject : + VOICE_IMAGE_MARKER_TEMPLATE_FALLBACK_SUBJECT; + int written = snprintf(out_prompt, + out_len, + VOICE_IMAGE_MARKER_TEMPLATE, + safe_subject); + if (written < 0) { + out_prompt[0] = '\0'; + return; + } + + if ((size_t)written >= out_len) { + out_prompt[out_len - 1] = '\0'; + } +} + +static void voice_try_preview_marker_png(const voice_image_generation_task_arg_t *task_arg, + const uint8_t *png, + size_t png_len) { + if (task_arg == NULL || png == NULL || png_len == 0) { + return; + } + + char preview_err[96] = {0}; + esp_err_t preview_rc = screen_preview_show_png(png, + png_len, + VOICE_IMAGE_PREVIEW_TIMEOUT_MS, + preview_err, + sizeof(preview_err)); + if (preview_rc == ESP_OK) { + ESP_LOGI(TAG, + "[stage] marker_image_preview_ok: dialog_id=%s png_bytes=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)png_len); + return; + } + + if (preview_rc == ESP_ERR_NOT_SUPPORTED) { + return; + } + + ESP_LOGW(TAG, + "[stage] marker_image_preview_failed: dialog_id=%s rc=0x%x msg=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)preview_rc, + preview_err[0] != '\0' ? preview_err : "preview failed"); +} + +static esp_err_t voice_submit_marker_generated_image(const voice_image_generation_task_arg_t *task_arg, + const image_generation_result_t *result, + char *err, + size_t err_len) { + if (task_arg == NULL || result == NULL || result->png == NULL || result->png_len == 0) { + voice_fill_err(err, err_len, "invalid image result"); + return ESP_ERR_INVALID_ARG; + } + + voice_try_preview_marker_png(task_arg, result->png, result->png_len); + + uint16_t raster_width = 0; + uint16_t raster_height = 0; + uint8_t *raster = NULL; + size_t raster_len = 0; + char decode_err[128] = {0}; + ESP_LOGI(TAG, + "[stage] marker_image_print_decode_start: dialog_id=%s request_id=%s png_bytes=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + result->request_id[0] != '\0' ? result->request_id : "-", + (unsigned)result->png_len); + esp_err_t decode_rc = raster_tools_convert_png_to_raster_384(result->png, + result->png_len, + true, + VOICE_IMAGE_PRINT_THRESHOLD, + false, + VOICE_IMAGE_PRINT_MAX_HEIGHT, + &raster_width, + &raster_height, + &raster, + &raster_len, + decode_err, + sizeof(decode_err)); + if (decode_rc != ESP_OK) { + voice_fill_err(err, + err_len, + decode_err[0] != '\0' ? decode_err : "decode generated image failed"); + ESP_LOGW(TAG, + "[stage] marker_image_print_decode_failed: dialog_id=%s rc=0x%x msg=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)decode_rc, + err != NULL && err[0] != '\0' ? err : "decode generated image failed"); + return decode_rc; + } + + ESP_LOGI(TAG, + "[stage] marker_image_print_decode_done: dialog_id=%s raster_size=%ux%u raster_bytes=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)raster_width, + (unsigned)raster_height, + (unsigned)raster_len); + + uint32_t job_id = 0; + char submit_err[128] = {0}; + printer_print_options_t print_opt = { + .direct_ignore_precheck = true, + }; + esp_err_t submit_rc = printer_protocol_submit_raster_job_ex(raster, + raster_len, + raster_width, + raster_height, + NULL, + &print_opt, + &job_id, + submit_err, + sizeof(submit_err)); + if (submit_rc != ESP_OK) { + voice_fill_err(err, + err_len, + submit_err[0] != '\0' ? submit_err : "submit print job failed"); + ESP_LOGW(TAG, + "[stage] marker_image_print_submit_failed: dialog_id=%s rc=0x%x msg=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)submit_rc, + err != NULL && err[0] != '\0' ? err : "submit print job failed"); + } else { + ESP_LOGI(TAG, + "[stage] marker_image_print_submit_ok: dialog_id=%s request_id=%s job_id=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + result->request_id[0] != '\0' ? result->request_id : "-", + (unsigned)job_id); + } + + free(raster); + return submit_rc; +} + +static void voice_image_generation_task(void *arg) { + voice_image_generation_task_arg_t *task_arg = (voice_image_generation_task_arg_t *)arg; + if (task_arg == NULL) { + vTaskDelete(NULL); + return; + } + + image_generation_request_t req = { + .prompt = task_arg->prompt, + .size = NULL, + .prompt_extend = false, + .has_seed = false, + .seed = 0, + .generation_timeout_ms = 0, + .download_timeout_ms = 0, + }; + + image_generation_result_t result = {0}; + image_generation_result_reset(&result); + + printer_status_poll_pause_token_t status_poll_pause_token = 0; + char gen_err[160] = {0}; + ESP_LOGI(TAG, + "[stage] marker_image_gen_start: dialog_id=%s prompt_len=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)strlen(task_arg->prompt)); + status_poll_pause_token = printer_protocol_status_poll_pause_acquire(); + esp_err_t rc = image_generation_generate_png(&req, &result, gen_err, sizeof(gen_err)); + printer_protocol_status_poll_pause_release(&status_poll_pause_token); + if (rc == ESP_OK) { + ESP_LOGI(TAG, + "[stage] marker_image_gen_done: dialog_id=%s request_id=%s size=%ux%u png_bytes=%u", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + result.request_id[0] != '\0' ? result.request_id : "-", + (unsigned)result.width, + (unsigned)result.height, + (unsigned)result.png_len); + + char submit_err[160] = {0}; + esp_err_t submit_rc = voice_submit_marker_generated_image(task_arg, + &result, + submit_err, + sizeof(submit_err)); + if (submit_rc == ESP_OK) { + voice_marker_image_generation_record_success(task_arg->prompt, + task_arg->dialog_id, + voice_now_ms()); + } else { + ESP_LOGW(TAG, + "[stage] marker_image_print_failed: dialog_id=%s rc=0x%x msg=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)submit_rc, + submit_err[0] != '\0' ? submit_err : "marker image print failed"); + } + } else { + ESP_LOGW(TAG, + "[stage] marker_image_gen_failed: dialog_id=%s rc=0x%x msg=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + (unsigned)rc, + gen_err[0] != '\0' ? gen_err : "image generation failed"); + } + + image_generation_result_free(&result); + voice_marker_image_generation_release(); + image_generation_schedule_prewarm(); + free(task_arg); + vTaskDelete(NULL); +} + +static void voice_schedule_marker_image_generation(const char *prompt, const char *dialog_id) { + if (prompt == NULL || prompt[0] == '\0') { + return; + } + + size_t prompt_len = strlen(prompt); + if (prompt_len > VOICE_IMAGE_MARKER_PROMPT_MAX_LEN) { + ESP_LOGW(TAG, + "[stage] marker_image_gen_skip: prompt too long, len=%u", + (unsigned)prompt_len); + return; + } + + uint32_t repeat_remain_ms = 0; + if (!voice_marker_image_generation_try_acquire(prompt, + dialog_id, + voice_now_ms(), + &repeat_remain_ms)) { + if (repeat_remain_ms > 0) { + ESP_LOGI(TAG, + "[stage] marker_image_gen_skip: duplicate prompt suppressed, remain_ms=%u", + (unsigned)repeat_remain_ms); + } else { + ESP_LOGI(TAG, "[stage] marker_image_gen_skip: previous marker task running"); + } + return; + } + + voice_image_generation_task_arg_t *task_arg = + (voice_image_generation_task_arg_t *)calloc(1, sizeof(*task_arg)); + if (task_arg == NULL) { + ESP_LOGW(TAG, "[stage] marker_image_gen_skip: no memory for task arg"); + voice_marker_image_generation_release(); + return; + } + + strlcpy(task_arg->prompt, prompt, sizeof(task_arg->prompt)); + if (dialog_id != NULL) { + strlcpy(task_arg->dialog_id, dialog_id, sizeof(task_arg->dialog_id)); + } + + BaseType_t ok = xTaskCreate(voice_image_generation_task, + "voice_img_gen", + VOICE_IMAGE_GEN_TASK_STACK, + task_arg, + VOICE_IMAGE_GEN_TASK_PRIO, + NULL); + if (ok != pdPASS) { + ESP_LOGW(TAG, "[stage] marker_image_gen_skip: create task failed"); + voice_marker_image_generation_release(); + free(task_arg); + return; + } + + ESP_LOGI(TAG, + "[stage] marker_image_gen_queued: dialog_id=%s prompt=%s", + task_arg->dialog_id[0] != '\0' ? task_arg->dialog_id : "-", + task_arg->prompt); +} + +void voice_marker_try_trigger_image_generation(const char *dialog_id, const char *final_text) { + if (final_text == NULL || final_text[0] == '\0') { + return; + } + + char first_sentence[VOICE_IMAGE_MARKER_FIRST_SENTENCE_MAX_LEN] = {0}; + if (!voice_extract_first_sentence_text(final_text, first_sentence, sizeof(first_sentence))) { + return; + } + + char marker_subject[VOICE_IMAGE_MARKER_PROMPT_MAX_LEN + 1] = {0}; + if (!voice_extract_marker_prompt(first_sentence, marker_subject, sizeof(marker_subject))) { + return; + } + + char templated_prompt[VOICE_IMAGE_MARKER_PROMPT_MAX_LEN + 1] = {0}; + voice_build_marker_image_prompt(marker_subject, + templated_prompt, + sizeof(templated_prompt)); + if (templated_prompt[0] == '\0') { + ESP_LOGW(TAG, "[stage] marker_image_gen_skip: build prompt failed"); + return; + } + + ESP_LOGI(TAG, + "[stage] marker_image_gen_detected: first_sentence=%s", + first_sentence); + ESP_LOGI(TAG, + "[stage] marker_image_gen_subject: keyword=%s", + marker_subject); + voice_log_text_preview("marker_image_gen_prompt_templated", templated_prompt); + voice_schedule_marker_image_generation(templated_prompt, dialog_id); +} + +bool voice_marker_image_generation_is_running(void) { + bool running = false; + portENTER_CRITICAL(&s_marker_image_gen_lock); + running = s_marker_image_gen_running; + portEXIT_CRITICAL(&s_marker_image_gen_lock); + return running; +} diff --git a/components/domain/src/voice_interaction_tasks.c b/components/domain/src/voice_interaction_tasks.c new file mode 100644 index 0000000..fea87c2 --- /dev/null +++ b/components/domain/src/voice_interaction_tasks.c @@ -0,0 +1,154 @@ +#include "voice_interaction_internal.h" + +#include + +#include "esp_audio_enc.h" +#include "esp_log.h" + +static const char *TAG = "voice_interaction"; + +void voice_uplink_task(void *arg) { + (void)arg; + + bool low_stack_warned = false; + UBaseType_t start_hwm = uxTaskGetStackHighWaterMark(NULL); + ESP_LOGI(TAG, "[stage] uplink_task_started: stack_hwm_words=%u", (unsigned)start_hwm); + + while (true) { + if (!low_stack_warned) { + UBaseType_t hwm = uxTaskGetStackHighWaterMark(NULL); + if (hwm < 256) { + low_stack_warned = true; + ESP_LOGW(TAG, "[stage] uplink_task_low_stack: hwm_words=%u", (unsigned)hwm); + } + } + + bool active = false; + bool connected = false; + bool started = false; + bool tap_active = false; + bool listening = false; + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + active = s_voice.session_active && !s_voice.stop_requested; + connected = s_voice.ws_connected; + started = s_voice.started; + tap_active = s_voice.tap_active; + listening = (s_voice.dialog_state == VOICE_DIALOG_STATE_LISTENING); + voice_unlock(); + } + + if (!active) { + break; + } + + if (!(connected && started && listening && tap_active)) { + vTaskDelay(pdMS_TO_TICKS(20)); + continue; + } + + char read_err[64] = {0}; + esp_err_t rc = voice_audio_read_pcm(s_voice.pcm_tx_buf, + (size_t)s_voice.opus_enc_in_size / VOICE_SAMPLE_BYTES, + VOICE_AUDIO_IO_TIMEOUT_MS, + read_err, + sizeof(read_err)); + if (rc != ESP_OK) { + memset(s_voice.pcm_tx_buf, 0, (size_t)s_voice.opus_enc_in_size); + } + + esp_audio_enc_in_frame_t in_frame = { + .buffer = (uint8_t *)s_voice.pcm_tx_buf, + .len = (uint32_t)s_voice.opus_enc_in_size, + }; + esp_audio_enc_out_frame_t out_frame = { + .buffer = s_voice.opus_tx_buf, + .len = (uint32_t)s_voice.opus_enc_out_size, + .encoded_bytes = 0, + }; + + esp_audio_err_t enc_err = esp_opus_enc_process(s_voice.opus_enc, &in_frame, &out_frame); + if (enc_err != ESP_AUDIO_ERR_OK || out_frame.encoded_bytes == 0) { + continue; + } + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + esp_websocket_client_handle_t ws = s_voice.ws; + bool ws_connected = s_voice.ws_connected; + voice_unlock(); + + bool transport_connected = (ws != NULL) && esp_websocket_client_is_connected(ws); + if (ws_connected && !transport_connected && voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + if (s_voice.ws_connected) { + s_voice.ws_connected = false; + s_voice.started = false; + s_voice.tap_active = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.last_event_ms = voice_now_ms(); + ESP_LOGW(TAG, "[stage] uplink_detected_ws_disconnected"); + } + voice_unlock(); + } + + if (ws != NULL && ws_connected && transport_connected) { + int ret = esp_websocket_client_send_bin(ws, + (const char *)s_voice.opus_tx_buf, + (int)out_frame.encoded_bytes, + pdMS_TO_TICKS(VOICE_WS_SEND_TIMEOUT_MS)); + if (ret >= 0) { + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.upstream_packets++; + s_voice.last_event_ms = voice_now_ms(); + voice_unlock(); + } + } + } + } + } + + bool delete_with_caps = false; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + delete_with_caps = s_voice.uplink_task_with_caps; + s_voice.uplink_task = NULL; + s_voice.uplink_task_with_caps = false; + voice_unlock(); + } + voice_delete_self_task(delete_with_caps); +} + +void voice_heartbeat_task(void *arg) { + (void)arg; + + while (true) { + bool active = false; + bool connected = false; + bool started = false; + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + active = s_voice.session_active && !s_voice.stop_requested; + connected = s_voice.ws_connected; + started = s_voice.started; + voice_unlock(); + } + + if (!active) { + break; + } + + if (connected && started) { + ESP_LOGI(TAG, "[stage] heartbeat_send"); + (void)voice_send_directive("continue-task", "HeartBeat", true); + } + + vTaskDelay(pdMS_TO_TICKS(CONFIG_TQ_VOICE_HEARTBEAT_SEC * 1000)); + } + + bool delete_with_caps = false; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + delete_with_caps = s_voice.heartbeat_task_with_caps; + s_voice.heartbeat_task = NULL; + s_voice.heartbeat_task_with_caps = false; + voice_unlock(); + } + voice_delete_self_task(delete_with_caps); +} diff --git a/components/domain/src/voice_interaction_ws.c b/components/domain/src/voice_interaction_ws.c new file mode 100644 index 0000000..ba28922 --- /dev/null +++ b/components/domain/src/voice_interaction_ws.c @@ -0,0 +1,340 @@ +#include "voice_interaction_internal.h" + +#include +#include + +#define cJSON_malloc voice_malloc_prefer_psram +#define cJSON_realloc voice_realloc_prefer_psram +#include "cJSON.h" +#undef cJSON_realloc +#undef cJSON_malloc +#include "esp_log.h" + +static const char *TAG = "voice_interaction"; + +static void *voice_cjson_malloc_hook(size_t size) { + return voice_malloc_prefer_psram(size); +} + +static void voice_cjson_init_hooks_once(void) { + static bool s_cjson_hooks_ready; + if (s_cjson_hooks_ready) { + return; + } + + cJSON_Hooks hooks = { + .malloc_fn = voice_cjson_malloc_hook, + .free_fn = free, + }; + cJSON_InitHooks(&hooks); + s_cjson_hooks_ready = true; +} + +void voice_interaction_ws_init_cjson_hooks(void) { + voice_cjson_init_hooks_once(); +} + +static char *voice_build_directive_message(const char *action, + const char *directive, + bool with_dialog_id) { + voice_cjson_init_hooks_once(); + + cJSON *root = cJSON_CreateObject(); + if (root == NULL) { + return NULL; + } + + cJSON *header = cJSON_AddObjectToObject(root, "header"); + cJSON_AddStringToObject(header, "action", action); + cJSON_AddStringToObject(header, "task_id", s_voice.task_id); + cJSON_AddStringToObject(header, "streaming", VOICE_STREAMING_MODE); + + cJSON *payload = cJSON_AddObjectToObject(root, "payload"); + cJSON *input = cJSON_AddObjectToObject(payload, "input"); + cJSON_AddStringToObject(input, "directive", directive); + if (with_dialog_id && s_voice.dialog_id[0] != '\0') { + cJSON_AddStringToObject(input, "dialog_id", s_voice.dialog_id); + } + + char *text = cJSON_PrintUnformatted(root); + cJSON_Delete(root); + return text; +} + +static char *voice_build_start_message(void) { + voice_cjson_init_hooks_once(); + + cJSON *root = cJSON_CreateObject(); + if (root == NULL) { + return NULL; + } + + cJSON *header = cJSON_AddObjectToObject(root, "header"); + cJSON_AddStringToObject(header, "action", "run-task"); + cJSON_AddStringToObject(header, "task_id", s_voice.task_id); + cJSON_AddStringToObject(header, "streaming", VOICE_STREAMING_MODE); + + cJSON *payload = cJSON_AddObjectToObject(root, "payload"); + cJSON_AddStringToObject(payload, "task_group", VOICE_TASK_GROUP); + cJSON_AddStringToObject(payload, "task", VOICE_TASK_NAME); + cJSON_AddStringToObject(payload, "function", VOICE_FUNCTION_NAME); + cJSON_AddStringToObject(payload, "model", VOICE_MODEL_NAME); + + cJSON *input = cJSON_AddObjectToObject(payload, "input"); + cJSON_AddStringToObject(input, "directive", "Start"); + cJSON_AddStringToObject(input, "workspace_id", CONFIG_TQ_VOICE_WORKSPACE_ID); + cJSON_AddStringToObject(input, "app_id", CONFIG_TQ_VOICE_APP_ID); + + cJSON *parameters = cJSON_AddObjectToObject(payload, "parameters"); + cJSON *upstream = cJSON_AddObjectToObject(parameters, "upstream"); + cJSON_AddStringToObject(upstream, "type", "AudioOnly"); + cJSON_AddStringToObject(upstream, "mode", "tap2talk"); + cJSON_AddStringToObject(upstream, "audio_format", "raw-opus"); + cJSON_AddNumberToObject(upstream, "sample_rate", CONFIG_TQ_VOICE_SAMPLE_RATE); + + cJSON *downstream = cJSON_AddObjectToObject(parameters, "downstream"); + cJSON_AddNumberToObject(downstream, "sample_rate", CONFIG_TQ_VOICE_SAMPLE_RATE); + cJSON_AddStringToObject(downstream, "audio_format", "raw-opus"); + cJSON_AddNumberToObject(downstream, "frame_size", CONFIG_TQ_VOICE_OPUS_FRAME_MS); + cJSON_AddNumberToObject(downstream, + "bit_rate", + CONFIG_TQ_VOICE_OPUS_BITRATE_KBPS); + if (strlen(CONFIG_TQ_VOICE_TTS_VOICE) > 0) { + cJSON_AddStringToObject(downstream, "voice", CONFIG_TQ_VOICE_TTS_VOICE); + } + + cJSON *client_info = cJSON_AddObjectToObject(parameters, "client_info"); + cJSON_AddStringToObject(client_info, "user_id", voice_safe_user_id()); + cJSON *device = cJSON_AddObjectToObject(client_info, "device"); + cJSON_AddStringToObject(device, "uuid", s_voice.device_uuid); + + char *text = cJSON_PrintUnformatted(root); + cJSON_Delete(root); + return text; +} + +static esp_err_t voice_send_text(const char *text, int len) { + if (text == NULL || len <= 0) { + return ESP_ERR_INVALID_ARG; + } + + esp_websocket_client_handle_t ws = NULL; + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + return ESP_ERR_TIMEOUT; + } + ws = s_voice.ws; + bool connected = s_voice.ws_connected; + voice_unlock(); + + bool transport_connected = (ws != NULL) && esp_websocket_client_is_connected(ws); + if (connected && !transport_connected && voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + if (s_voice.ws_connected) { + s_voice.ws_connected = false; + s_voice.started = false; + s_voice.tap_active = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.last_event_ms = voice_now_ms(); + ESP_LOGW(TAG, "[stage] ws_state_reconciled: transport disconnected"); + } + voice_unlock(); + } + + if (ws == NULL || !connected || !transport_connected) { + ESP_LOGW(TAG, "[stage] ws_send_text skipped: ws=%p connected=%d len=%d", (void *)ws, connected, len); + return ESP_ERR_INVALID_STATE; + } + + int ret = esp_websocket_client_send_text(ws, + text, + len, + pdMS_TO_TICKS(VOICE_WS_SEND_TIMEOUT_MS)); + if (ret < 0) { + ESP_LOGW(TAG, "[stage] ws_send_text failed: len=%d", len); + return ESP_FAIL; + } + ESP_LOGI(TAG, "[stage] ws_send_text ok: len=%d", len); + return ESP_OK; +} + +esp_err_t voice_send_directive(const char *action, + const char *directive, + bool with_dialog_id) { + char *text = NULL; + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + return ESP_ERR_TIMEOUT; + } + text = voice_build_directive_message(action, directive, with_dialog_id); + voice_unlock(); + + if (text == NULL) { + return ESP_ERR_NO_MEM; + } + + esp_err_t err = voice_send_text(text, (int)strlen(text)); + ESP_LOGI(TAG, + "[stage] directive: action=%s directive=%s with_dialog_id=%d result=%s", + action, + directive, + with_dialog_id, + esp_err_to_name(err)); + cJSON_free(text); + return err; +} + +static void voice_handle_text_chunk(esp_websocket_event_data_t *data) { + if (data->payload_offset == 0) { + free(s_voice.text_agg); + s_voice.text_agg = NULL; + s_voice.text_agg_size = 0; + + if (data->payload_len <= 0 || data->payload_len > 4096) { + return; + } + + s_voice.text_agg = (uint8_t *)voice_calloc_prefer_psram(1, (size_t)data->payload_len + 1); + if (s_voice.text_agg == NULL) { + ESP_LOGW(TAG, "[stage] text_agg_alloc_failed: len=%d", data->payload_len); + return; + } + s_voice.text_agg_size = (size_t)data->payload_len; + } + + if (s_voice.text_agg == NULL || s_voice.text_agg_size == 0) { + return; + } + + if ((size_t)data->payload_offset + (size_t)data->data_len > s_voice.text_agg_size) { + free(s_voice.text_agg); + s_voice.text_agg = NULL; + s_voice.text_agg_size = 0; + return; + } + + memcpy(s_voice.text_agg + data->payload_offset, data->data_ptr, (size_t)data->data_len); + + bool complete = data->fin && + ((size_t)data->payload_offset + (size_t)data->data_len == s_voice.text_agg_size); + if (!complete) { + return; + } + + voice_ws_protocol_handle_text_message((const char *)s_voice.text_agg, s_voice.text_agg_size); + free(s_voice.text_agg); + s_voice.text_agg = NULL; + s_voice.text_agg_size = 0; +} + +static void voice_handle_binary_chunk(esp_websocket_event_data_t *data) { + if (data->payload_offset == 0) { + free(s_voice.bin_agg); + s_voice.bin_agg = NULL; + s_voice.bin_agg_size = 0; + + if (data->payload_len <= 0 || data->payload_len > 16384) { + return; + } + + s_voice.bin_agg = (uint8_t *)voice_malloc_prefer_psram((size_t)data->payload_len); + if (s_voice.bin_agg == NULL) { + ESP_LOGW(TAG, "[stage] bin_agg_alloc_failed: len=%d", data->payload_len); + return; + } + s_voice.bin_agg_size = (size_t)data->payload_len; + } + + if (s_voice.bin_agg == NULL || s_voice.bin_agg_size == 0) { + return; + } + + if ((size_t)data->payload_offset + (size_t)data->data_len > s_voice.bin_agg_size) { + free(s_voice.bin_agg); + s_voice.bin_agg = NULL; + s_voice.bin_agg_size = 0; + return; + } + + memcpy(s_voice.bin_agg + data->payload_offset, data->data_ptr, (size_t)data->data_len); + + bool complete = data->fin && + ((size_t)data->payload_offset + (size_t)data->data_len == s_voice.bin_agg_size); + if (!complete) { + return; + } + + voice_ws_audio_handle_downstream_packet(s_voice.bin_agg, s_voice.bin_agg_size); + free(s_voice.bin_agg); + s_voice.bin_agg = NULL; + s_voice.bin_agg_size = 0; +} + +void voice_websocket_event_handler(void *handler_args, + esp_event_base_t base, + int32_t event_id, + void *event_data) { + (void)handler_args; + (void)base; + + UBaseType_t ws_hwm = uxTaskGetStackHighWaterMark(NULL); + if (!s_voice.ws_low_stack_warned && ws_hwm < 256) { + s_voice.ws_low_stack_warned = true; + ESP_LOGW(TAG, "[stage] ws_task_low_stack: hwm_words=%u", (unsigned)ws_hwm); + } + + esp_websocket_event_data_t *data = (esp_websocket_event_data_t *)event_data; + switch ((esp_websocket_event_id_t)event_id) { + case WEBSOCKET_EVENT_CONNECTED: { + ESP_LOGI(TAG, "[stage] ws_connected"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.ws_connected = true; + s_voice.last_event_ms = voice_now_ms(); + voice_unlock(); + } + + char *start_msg = NULL; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + start_msg = voice_build_start_message(); + voice_unlock(); + } + if (start_msg != NULL) { + esp_err_t send_err = voice_send_text(start_msg, (int)strlen(start_msg)); + ESP_LOGI(TAG, "[stage] start_message_sent: result=%s", esp_err_to_name(send_err)); + cJSON_free(start_msg); + } else { + ESP_LOGE(TAG, "[stage] start_message_build_failed"); + } + break; + } + case WEBSOCKET_EVENT_DISCONNECTED: + ESP_LOGW(TAG, "[stage] ws_disconnected"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.ws_connected = false; + s_voice.started = false; + s_voice.tap_active = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.last_event_ms = voice_now_ms(); + voice_unlock(); + } + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_MS, "ws_disconnected_close"); + break; + case WEBSOCKET_EVENT_DATA: + if (data == NULL || data->data_ptr == NULL || data->data_len <= 0) { + break; + } + if (data->op_code == WS_TRANSPORT_OPCODES_TEXT) { + voice_handle_text_chunk(data); + } else if (data->op_code == WS_TRANSPORT_OPCODES_BINARY) { + voice_handle_binary_chunk(data); + } + break; + case WEBSOCKET_EVENT_ERROR: + ESP_LOGW(TAG, "[stage] ws_error"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_set_last_error_locked("websocket error"); + s_voice.last_event_ms = voice_now_ms(); + voice_unlock(); + } + break; + default: + break; + } +} diff --git a/components/domain/src/voice_interaction_ws_audio.c b/components/domain/src/voice_interaction_ws_audio.c new file mode 100644 index 0000000..518bfbe --- /dev/null +++ b/components/domain/src/voice_interaction_ws_audio.c @@ -0,0 +1,99 @@ +#include "voice_interaction_internal.h" + +#include "esp_audio_dec.h" +#include "esp_log.h" + +static const char *TAG = "voice_interaction"; + +void voice_ws_audio_handle_downstream_packet(const uint8_t *data, size_t len) { + if (data == NULL || len == 0) { + return; + } + + if (!voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + return; + } + + void *opus_dec = s_voice.opus_dec; + uint8_t *pcm_buf = s_voice.pcm_rx_buf; + size_t pcm_buf_size = s_voice.pcm_rx_buf_size; + voice_unlock(); + + if (opus_dec == NULL || pcm_buf == NULL || pcm_buf_size == 0) { + return; + } + + esp_audio_dec_in_raw_t raw = { + .buffer = (uint8_t *)data, + .len = (uint32_t)len, + .consumed = 0, + }; + + while (raw.len > 0) { + esp_audio_dec_out_frame_t out = { + .buffer = pcm_buf, + .len = (uint32_t)pcm_buf_size, + .needed_size = 0, + .decoded_size = 0, + }; + esp_audio_dec_info_t dec_info = {0}; + + esp_audio_err_t ret = esp_opus_dec_decode(opus_dec, &raw, &out, &dec_info); + if (ret == ESP_AUDIO_ERR_BUFF_NOT_ENOUGH) { + if (out.needed_size > pcm_buf_size) { + uint8_t *new_buf = (uint8_t *)voice_realloc_prefer_psram(pcm_buf, out.needed_size); + if (new_buf == NULL) { + ESP_LOGE(TAG, "No memory to extend pcm rx buffer to %u", out.needed_size); + break; + } + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.pcm_rx_buf = new_buf; + s_voice.pcm_rx_buf_size = out.needed_size; + voice_unlock(); + } + pcm_buf = new_buf; + pcm_buf_size = out.needed_size; + continue; + } + break; + } + + if (ret != ESP_AUDIO_ERR_OK) { + ESP_LOGW(TAG, "opus decode failed: %d", ret); + break; + } + + if (out.decoded_size > 0) { + char audio_err[64] = {0}; + size_t samples = (size_t)out.decoded_size / VOICE_SAMPLE_BYTES; + esp_err_t write_err = voice_audio_write_pcm((const int16_t *)out.buffer, + samples, + VOICE_AUDIO_IO_TIMEOUT_MS, + audio_err, + sizeof(audio_err)); + if (write_err == ESP_OK && voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + int64_t now_ms = voice_now_ms(); + int64_t pcm_ms = ((int64_t)samples * 1000 + + (int64_t)CONFIG_TQ_VOICE_SAMPLE_RATE - 1) / + (int64_t)CONFIG_TQ_VOICE_SAMPLE_RATE; + int64_t base_ms = s_voice.playback_deadline_ms > now_ms ? + s_voice.playback_deadline_ms : now_ms; + s_voice.playback_deadline_ms = base_ms + pcm_ms + VOICE_AUDIO_DRAIN_MARGIN_MS; + s_voice.last_downstream_ms = now_ms; + voice_unlock(); + } + } + + if (raw.consumed == 0 || raw.consumed > raw.len) { + break; + } + raw.buffer += raw.consumed; + raw.len -= raw.consumed; + } + + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + s_voice.downstream_packets++; + s_voice.last_event_ms = voice_now_ms(); + voice_unlock(); + } +} diff --git a/components/domain/src/voice_interaction_ws_protocol.c b/components/domain/src/voice_interaction_ws_protocol.c new file mode 100644 index 0000000..97572ef --- /dev/null +++ b/components/domain/src/voice_interaction_ws_protocol.c @@ -0,0 +1,252 @@ +#include "voice_interaction_internal.h" + +#include + +#define cJSON_malloc voice_malloc_prefer_psram +#define cJSON_realloc voice_realloc_prefer_psram +#include "cJSON.h" +#undef cJSON_realloc +#undef cJSON_malloc +#include "esp_log.h" + +static const char *TAG = "voice_interaction"; + +static const char *voice_get_json_str(cJSON *obj, const char *name) { + if (obj == NULL || name == NULL) { + return NULL; + } + + cJSON *item = cJSON_GetObjectItemCaseSensitive(obj, name); + if (cJSON_IsString(item) && item->valuestring != NULL) { + return item->valuestring; + } + return NULL; +} + +static bool voice_get_json_bool(cJSON *obj, const char *name, bool *out_value) { + if (obj == NULL || name == NULL || out_value == NULL) { + return false; + } + + cJSON *item = cJSON_GetObjectItemCaseSensitive(obj, name); + if (!cJSON_IsBool(item)) { + return false; + } + *out_value = cJSON_IsTrue(item); + return true; +} + +static void voice_log_final_text(const char *stage, const char *text) { + if (stage == NULL || text == NULL || text[0] == '\0') { + return; + } + + size_t len = strlen(text); + const int preview = 240; + ESP_LOGI(TAG, + "[stage] %s: len=%u text=%.*s%s", + stage, + (unsigned)len, + preview, + text, + (len > (size_t)preview) ? "..." : ""); +} + +static void voice_handle_output_event(cJSON *output) { + const char *event_name = voice_get_json_str(output, "event"); + if (event_name == NULL) { + return; + } + + const char *dialog_id = voice_get_json_str(output, "dialog_id"); + const char *state = NULL; + if (strcmp(event_name, "DialogStateChanged") == 0) { + state = voice_get_json_str(output, "state"); + } + ESP_LOGI(TAG, + "[stage] ws_event_output: event=%s dialog_id=%s state=%s", + event_name, + dialog_id != NULL ? dialog_id : "-", + state != NULL ? state : "-"); + + bool finished = false; + bool has_finished = voice_get_json_bool(output, "finished", &finished); + const char *responding_final_text = NULL; + bool should_check_marker_in_first_sentence = false; + if (has_finished && finished) { + if (strcmp(event_name, "SpeechContent") == 0) { + voice_log_final_text("asr_final_text", voice_get_json_str(output, "text")); + } else if (strcmp(event_name, "RespondingContent") == 0) { + const char *final_text = voice_get_json_str(output, "text"); + if (final_text == NULL || final_text[0] == '\0') { + final_text = voice_get_json_str(output, "spoken"); + } + voice_log_final_text("response_final_text", final_text); + responding_final_text = final_text; + if (responding_final_text != NULL && responding_final_text[0] != '\0' && + voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + if (!s_voice.response_first_sentence_checked) { + s_voice.response_first_sentence_checked = true; + should_check_marker_in_first_sentence = true; + } + voice_unlock(); + } + } + } + + bool should_close_audio = false; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + if (dialog_id != NULL) { + strlcpy(s_voice.dialog_id, dialog_id, sizeof(s_voice.dialog_id)); + } + s_voice.last_event_ms = voice_now_ms(); + + if (strcmp(event_name, "Started") == 0) { + s_voice.started = true; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.response_first_sentence_checked = false; + ESP_LOGI(TAG, "[stage] session_started: dialog_id=%s", s_voice.dialog_id); + } else if (strcmp(event_name, "DialogStateChanged") == 0) { + if (state != NULL) { + voice_dialog_state_t prev_state = s_voice.dialog_state; + if (strcmp(state, "Listening") == 0) { + s_voice.dialog_state = VOICE_DIALOG_STATE_LISTENING; + if (prev_state != VOICE_DIALOG_STATE_LISTENING) { + s_voice.response_first_sentence_checked = false; + } + } else if (strcmp(state, "Thinking") == 0) { + s_voice.dialog_state = VOICE_DIALOG_STATE_THINKING; + if (prev_state != VOICE_DIALOG_STATE_THINKING) { + s_voice.response_first_sentence_checked = false; + } + } else if (strcmp(state, "Responding") == 0) { + s_voice.dialog_state = VOICE_DIALOG_STATE_RESPONDING; + if (prev_state != VOICE_DIALOG_STATE_RESPONDING) { + s_voice.response_first_sentence_checked = false; + } + } + } + ESP_LOGI(TAG, + "[stage] dialog_state_changed: state=%s current=%s", + state != NULL ? state : "-", + voice_interaction_dialog_state_str(s_voice.dialog_state)); + } else if (strcmp(event_name, "SpeechEnded") == 0) { + s_voice.tap_active = false; + ESP_LOGI(TAG, "[stage] speech_ended: mark single_round_input_done"); + } else if (strcmp(event_name, "RespondingEnded") == 0) { + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + ESP_LOGI(TAG, "[stage] responding_ended: wait_local_playback_before_ack"); + } else if (strcmp(event_name, "Stopped") == 0) { + s_voice.started = false; + s_voice.tap_active = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.response_first_sentence_checked = false; + should_close_audio = true; + ESP_LOGI(TAG, "[stage] session_stopped_by_server"); + } else if (strcmp(event_name, "Error") == 0) { + const char *error_msg = voice_get_json_str(output, "error_message"); + if (error_msg != NULL) { + voice_set_last_error_locked(error_msg); + ESP_LOGW(TAG, "[stage] server_error: %s", error_msg); + } + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + s_voice.tap_active = false; + s_voice.response_first_sentence_checked = false; + should_close_audio = true; + } + voice_unlock(); + } + + if (should_close_audio) { + voice_close_audio_with_drain(VOICE_AUDIO_DRAIN_WAIT_MS, "server_event_close"); + } + + if (should_check_marker_in_first_sentence) { + voice_marker_try_trigger_image_generation(dialog_id, responding_final_text); + } + + if (strcmp(event_name, "RespondingStarted") == 0) { + (void)voice_send_directive("continue-task", "LocalRespondingStarted", true); + } else if (strcmp(event_name, "RespondingEnded") == 0) { + uint32_t playback_wait_ms = VOICE_AUDIO_DRAIN_WAIT_MS; + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + int64_t now_ms = voice_now_ms(); + int64_t deadline_ms = s_voice.playback_deadline_ms; + voice_unlock(); + + if (deadline_ms > now_ms) { + int64_t remain_ms = (deadline_ms - now_ms) + VOICE_AUDIO_DRAIN_QUIET_MS + 120; + if (remain_ms > (int64_t)playback_wait_ms) { + if (remain_ms > 12000) { + playback_wait_ms = 12000; + } else { + playback_wait_ms = (uint32_t)remain_ms; + } + } + } + } + ESP_LOGI(TAG, "[stage] responding_ended_local_playback_wait: timeout_ms=%u", (unsigned)playback_wait_ms); + voice_wait_audio_playback_done(playback_wait_ms, + "responding_ended_local_playback"); + (void)voice_send_directive("continue-task", "LocalRespondingEnded", true); + (void)voice_send_directive("finish-task", "Stop", true); + } +} + +void voice_ws_protocol_handle_text_message(const char *text, size_t len) { + if (text == NULL || len == 0) { + return; + } + + voice_interaction_ws_init_cjson_hooks(); + + cJSON *root = cJSON_ParseWithLength(text, len); + if (root == NULL) { + ESP_LOGW(TAG, "Invalid ws text payload"); + return; + } + + cJSON *header = cJSON_GetObjectItemCaseSensitive(root, "header"); + const char *header_event = voice_get_json_str(header, "event"); + + cJSON *payload = cJSON_GetObjectItemCaseSensitive(root, "payload"); + cJSON *output = NULL; + if (payload != NULL) { + output = cJSON_GetObjectItemCaseSensitive(payload, "output"); + } + + if (header != NULL) { + cJSON *status_code = cJSON_GetObjectItemCaseSensitive(header, "status_code"); + cJSON *status_msg = cJSON_GetObjectItemCaseSensitive(header, "status_message"); + if (cJSON_IsNumber(status_code) && status_code->valueint >= 400) { + ESP_LOGW(TAG, + "[stage] ws_header_error: status_code=%d status_message=%s", + status_code->valueint, + (cJSON_IsString(status_msg) && status_msg->valuestring != NULL) ? status_msg->valuestring : "-"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + if (cJSON_IsString(status_msg) && status_msg->valuestring != NULL) { + voice_set_last_error_locked(status_msg->valuestring); + } else { + voice_set_last_error_locked("websocket status error"); + } + voice_unlock(); + } + } + } + + if (output != NULL) { + voice_handle_output_event(output); + } else if (header_event != NULL && strcmp(header_event, "task-failed") == 0) { + const char *error_msg = voice_get_json_str(header, "error_message"); + ESP_LOGW(TAG, "[stage] ws_task_failed: %s", error_msg != NULL ? error_msg : "task failed"); + if (voice_lock(VOICE_STATUS_LOCK_TIMEOUT_MS)) { + voice_set_last_error_locked(error_msg != NULL ? error_msg : "task failed"); + s_voice.started = false; + s_voice.tap_active = false; + s_voice.dialog_state = VOICE_DIALOG_STATE_IDLE; + voice_unlock(); + } + } + + cJSON_Delete(root); +} diff --git a/components/domain/third_party/qrcodegen.c b/components/domain/third_party/qrcodegen.c new file mode 100644 index 0000000..34f1002 --- /dev/null +++ b/components/domain/third_party/qrcodegen.c @@ -0,0 +1,1027 @@ +/* + * QR Code generator library (C) + * + * Copyright (c) Project Nayuki. (MIT License) + * https://www.nayuki.io/page/qr-code-generator-library + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to + * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of + * the Software, and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * - The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * - The Software is provided "as is", without warranty of any kind, express or + * implied, including but not limited to the warranties of merchantability, + * fitness for a particular purpose and noninfringement. In no event shall the + * authors or copyright holders be liable for any claim, damages or other + * liability, whether in an action of contract, tort or otherwise, arising from, + * out of or in connection with the Software or the use or other dealings in the + * Software. + */ + +#include +#include +#include +#include +#include "qrcodegen.h" + +#ifndef QRCODEGEN_TEST + #define testable static // Keep functions private +#else + #define testable // Expose private functions +#endif + + +/*---- Forward declarations for private functions ----*/ + +// Regarding all public and private functions defined in this source file: +// - They require all pointer/array arguments to be not null unless the array length is zero. +// - They only read input scalar/array arguments, write to output pointer/array +// arguments, and return scalar values; they are "pure" functions. +// - They don't read mutable global variables or write to any global variables. +// - They don't perform I/O, read the clock, print to console, etc. +// - They allocate a small and constant amount of stack memory. +// - They don't allocate or free any memory on the heap. +// - They don't recurse or mutually recurse. All the code +// could be inlined into the top-level public functions. +// - They run in at most quadratic time with respect to input arguments. +// Most functions run in linear time, and some in constant time. +// There are no unbounded loops or non-obvious termination conditions. +// - They are completely thread-safe if the caller does not give the +// same writable buffer to concurrent calls to these functions. + +testable void appendBitsToBuffer(unsigned int val, int numBits, uint8_t buffer[], int *bitLen); + +testable void addEccAndInterleave(uint8_t data[], int version, enum qrcodegen_Ecc ecl, uint8_t result[]); +testable int getNumDataCodewords(int version, enum qrcodegen_Ecc ecl); +testable int getNumRawDataModules(int ver); + +testable void reedSolomonComputeDivisor(int degree, uint8_t result[]); +testable void reedSolomonComputeRemainder(const uint8_t data[], int dataLen, + const uint8_t generator[], int degree, uint8_t result[]); +testable uint8_t reedSolomonMultiply(uint8_t x, uint8_t y); + +testable void initializeFunctionModules(int version, uint8_t qrcode[]); +static void drawLightFunctionModules(uint8_t qrcode[], int version); +static void drawFormatBits(enum qrcodegen_Ecc ecl, enum qrcodegen_Mask mask, uint8_t qrcode[]); +testable int getAlignmentPatternPositions(int version, uint8_t result[7]); +static void fillRectangle(int left, int top, int width, int height, uint8_t qrcode[]); + +static void drawCodewords(const uint8_t data[], int dataLen, uint8_t qrcode[]); +static void applyMask(const uint8_t functionModules[], uint8_t qrcode[], enum qrcodegen_Mask mask); +static long getPenaltyScore(const uint8_t qrcode[]); +static int finderPenaltyCountPatterns(const int runHistory[7], int qrsize); +static int finderPenaltyTerminateAndCount(bool currentRunColor, int currentRunLength, int runHistory[7], int qrsize); +static void finderPenaltyAddHistory(int currentRunLength, int runHistory[7], int qrsize); + +testable bool getModuleBounded(const uint8_t qrcode[], int x, int y); +testable void setModuleBounded(uint8_t qrcode[], int x, int y, bool isDark); +testable void setModuleUnbounded(uint8_t qrcode[], int x, int y, bool isDark); +static bool getBit(int x, int i); + +testable int calcSegmentBitLength(enum qrcodegen_Mode mode, size_t numChars); +testable int getTotalBits(const struct qrcodegen_Segment segs[], size_t len, int version); +static int numCharCountBits(enum qrcodegen_Mode mode, int version); + + + +/*---- Private tables of constants ----*/ + +// The set of all legal characters in alphanumeric mode, where each character +// value maps to the index in the string. For checking text and encoding segments. +static const char *ALPHANUMERIC_CHARSET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ $%*+-./:"; + +// Sentinel value for use in only some functions. +#define LENGTH_OVERFLOW -1 + +// For generating error correction codes. +testable const int8_t ECC_CODEWORDS_PER_BLOCK[4][41] = { + // Version: (note that index 0 is for padding, and is set to an illegal value) + //0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40 Error correction level + {-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30}, // Low + {-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28}, // Medium + {-1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30}, // Quartile + {-1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30}, // High +}; + +#define qrcodegen_REED_SOLOMON_DEGREE_MAX 30 // Based on the table above + +// For generating error correction codes. +testable const int8_t NUM_ERROR_CORRECTION_BLOCKS[4][41] = { + // Version: (note that index 0 is for padding, and is set to an illegal value) + //0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40 Error correction level + {-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25}, // Low + {-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49}, // Medium + {-1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68}, // Quartile + {-1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81}, // High +}; + +// For automatic mask pattern selection. +static const int PENALTY_N1 = 3; +static const int PENALTY_N2 = 3; +static const int PENALTY_N3 = 40; +static const int PENALTY_N4 = 10; + + + +/*---- High-level QR Code encoding functions ----*/ + +// Public function - see documentation comment in header file. +bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode[], + enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl) { + + size_t textLen = strlen(text); + if (textLen == 0) + return qrcodegen_encodeSegmentsAdvanced(NULL, 0, ecl, minVersion, maxVersion, mask, boostEcl, tempBuffer, qrcode); + size_t bufLen = (size_t)qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion); + + struct qrcodegen_Segment seg; + if (qrcodegen_isNumeric(text)) { + if (qrcodegen_calcSegmentBufferSize(qrcodegen_Mode_NUMERIC, textLen) > bufLen) + goto fail; + seg = qrcodegen_makeNumeric(text, tempBuffer); + } else if (qrcodegen_isAlphanumeric(text)) { + if (qrcodegen_calcSegmentBufferSize(qrcodegen_Mode_ALPHANUMERIC, textLen) > bufLen) + goto fail; + seg = qrcodegen_makeAlphanumeric(text, tempBuffer); + } else { + if (textLen > bufLen) + goto fail; + for (size_t i = 0; i < textLen; i++) + tempBuffer[i] = (uint8_t)text[i]; + seg.mode = qrcodegen_Mode_BYTE; + seg.bitLength = calcSegmentBitLength(seg.mode, textLen); + if (seg.bitLength == LENGTH_OVERFLOW) + goto fail; + seg.numChars = (int)textLen; + seg.data = tempBuffer; + } + return qrcodegen_encodeSegmentsAdvanced(&seg, 1, ecl, minVersion, maxVersion, mask, boostEcl, tempBuffer, qrcode); + +fail: + qrcode[0] = 0; // Set size to invalid value for safety + return false; +} + + +// Public function - see documentation comment in header file. +bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcode[], + enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl) { + + struct qrcodegen_Segment seg; + seg.mode = qrcodegen_Mode_BYTE; + seg.bitLength = calcSegmentBitLength(seg.mode, dataLen); + if (seg.bitLength == LENGTH_OVERFLOW) { + qrcode[0] = 0; // Set size to invalid value for safety + return false; + } + seg.numChars = (int)dataLen; + seg.data = dataAndTemp; + return qrcodegen_encodeSegmentsAdvanced(&seg, 1, ecl, minVersion, maxVersion, mask, boostEcl, dataAndTemp, qrcode); +} + + +// Appends the given number of low-order bits of the given value to the given byte-based +// bit buffer, increasing the bit length. Requires 0 <= numBits <= 16 and val < 2^numBits. +testable void appendBitsToBuffer(unsigned int val, int numBits, uint8_t buffer[], int *bitLen) { + assert(0 <= numBits && numBits <= 16 && (unsigned long)val >> numBits == 0); + for (int i = numBits - 1; i >= 0; i--, (*bitLen)++) + buffer[*bitLen >> 3] |= ((val >> i) & 1) << (7 - (*bitLen & 7)); +} + + + +/*---- Low-level QR Code encoding functions ----*/ + +// Public function - see documentation comment in header file. +bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len, + enum qrcodegen_Ecc ecl, uint8_t tempBuffer[], uint8_t qrcode[]) { + return qrcodegen_encodeSegmentsAdvanced(segs, len, ecl, + qrcodegen_VERSION_MIN, qrcodegen_VERSION_MAX, qrcodegen_Mask_AUTO, true, tempBuffer, qrcode); +} + + +// Public function - see documentation comment in header file. +bool qrcodegen_encodeSegmentsAdvanced(const struct qrcodegen_Segment segs[], size_t len, enum qrcodegen_Ecc ecl, + int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl, uint8_t tempBuffer[], uint8_t qrcode[]) { + assert(segs != NULL || len == 0); + assert(qrcodegen_VERSION_MIN <= minVersion && minVersion <= maxVersion && maxVersion <= qrcodegen_VERSION_MAX); + assert(0 <= (int)ecl && (int)ecl <= 3 && -1 <= (int)mask && (int)mask <= 7); + + // Find the minimal version number to use + int version, dataUsedBits; + for (version = minVersion; ; version++) { + int dataCapacityBits = getNumDataCodewords(version, ecl) * 8; // Number of data bits available + dataUsedBits = getTotalBits(segs, len, version); + if (dataUsedBits != LENGTH_OVERFLOW && dataUsedBits <= dataCapacityBits) + break; // This version number is found to be suitable + if (version >= maxVersion) { // All versions in the range could not fit the given data + qrcode[0] = 0; // Set size to invalid value for safety + return false; + } + } + assert(dataUsedBits != LENGTH_OVERFLOW); + + // Increase the error correction level while the data still fits in the current version number + for (int i = (int)qrcodegen_Ecc_MEDIUM; i <= (int)qrcodegen_Ecc_HIGH; i++) { // From low to high + if (boostEcl && dataUsedBits <= getNumDataCodewords(version, (enum qrcodegen_Ecc)i) * 8) + ecl = (enum qrcodegen_Ecc)i; + } + + // Concatenate all segments to create the data bit string + memset(qrcode, 0, (size_t)qrcodegen_BUFFER_LEN_FOR_VERSION(version) * sizeof(qrcode[0])); + int bitLen = 0; + for (size_t i = 0; i < len; i++) { + const struct qrcodegen_Segment *seg = &segs[i]; + appendBitsToBuffer((unsigned int)seg->mode, 4, qrcode, &bitLen); + appendBitsToBuffer((unsigned int)seg->numChars, numCharCountBits(seg->mode, version), qrcode, &bitLen); + for (int j = 0; j < seg->bitLength; j++) { + int bit = (seg->data[j >> 3] >> (7 - (j & 7))) & 1; + appendBitsToBuffer((unsigned int)bit, 1, qrcode, &bitLen); + } + } + assert(bitLen == dataUsedBits); + + // Add terminator and pad up to a byte if applicable + int dataCapacityBits = getNumDataCodewords(version, ecl) * 8; + assert(bitLen <= dataCapacityBits); + int terminatorBits = dataCapacityBits - bitLen; + if (terminatorBits > 4) + terminatorBits = 4; + appendBitsToBuffer(0, terminatorBits, qrcode, &bitLen); + appendBitsToBuffer(0, (8 - bitLen % 8) % 8, qrcode, &bitLen); + assert(bitLen % 8 == 0); + + // Pad with alternating bytes until data capacity is reached + for (uint8_t padByte = 0xEC; bitLen < dataCapacityBits; padByte ^= 0xEC ^ 0x11) + appendBitsToBuffer(padByte, 8, qrcode, &bitLen); + + // Compute ECC, draw modules + addEccAndInterleave(qrcode, version, ecl, tempBuffer); + initializeFunctionModules(version, qrcode); + drawCodewords(tempBuffer, getNumRawDataModules(version) / 8, qrcode); + drawLightFunctionModules(qrcode, version); + initializeFunctionModules(version, tempBuffer); + + // Do masking + if (mask == qrcodegen_Mask_AUTO) { // Automatically choose best mask + long minPenalty = LONG_MAX; + for (int i = 0; i < 8; i++) { + enum qrcodegen_Mask msk = (enum qrcodegen_Mask)i; + applyMask(tempBuffer, qrcode, msk); + drawFormatBits(ecl, msk, qrcode); + long penalty = getPenaltyScore(qrcode); + if (penalty < minPenalty) { + mask = msk; + minPenalty = penalty; + } + applyMask(tempBuffer, qrcode, msk); // Undoes the mask due to XOR + } + } + assert(0 <= (int)mask && (int)mask <= 7); + applyMask(tempBuffer, qrcode, mask); // Apply the final choice of mask + drawFormatBits(ecl, mask, qrcode); // Overwrite old format bits + return true; +} + + + +/*---- Error correction code generation functions ----*/ + +// Appends error correction bytes to each block of the given data array, then interleaves +// bytes from the blocks and stores them in the result array. data[0 : dataLen] contains +// the input data. data[dataLen : rawCodewords] is used as a temporary work area and will +// be clobbered by this function. The final answer is stored in result[0 : rawCodewords]. +testable void addEccAndInterleave(uint8_t data[], int version, enum qrcodegen_Ecc ecl, uint8_t result[]) { + // Calculate parameter numbers + assert(0 <= (int)ecl && (int)ecl < 4 && qrcodegen_VERSION_MIN <= version && version <= qrcodegen_VERSION_MAX); + int numBlocks = NUM_ERROR_CORRECTION_BLOCKS[(int)ecl][version]; + int blockEccLen = ECC_CODEWORDS_PER_BLOCK [(int)ecl][version]; + int rawCodewords = getNumRawDataModules(version) / 8; + int dataLen = getNumDataCodewords(version, ecl); + int numShortBlocks = numBlocks - rawCodewords % numBlocks; + int shortBlockDataLen = rawCodewords / numBlocks - blockEccLen; + + // Split data into blocks, calculate ECC, and interleave + // (not concatenate) the bytes into a single sequence + uint8_t rsdiv[qrcodegen_REED_SOLOMON_DEGREE_MAX]; + reedSolomonComputeDivisor(blockEccLen, rsdiv); + const uint8_t *dat = data; + for (int i = 0; i < numBlocks; i++) { + int datLen = shortBlockDataLen + (i < numShortBlocks ? 0 : 1); + uint8_t *ecc = &data[dataLen]; // Temporary storage + reedSolomonComputeRemainder(dat, datLen, rsdiv, blockEccLen, ecc); + for (int j = 0, k = i; j < datLen; j++, k += numBlocks) { // Copy data + if (j == shortBlockDataLen) + k -= numShortBlocks; + result[k] = dat[j]; + } + for (int j = 0, k = dataLen + i; j < blockEccLen; j++, k += numBlocks) // Copy ECC + result[k] = ecc[j]; + dat += datLen; + } +} + + +// Returns the number of 8-bit codewords that can be used for storing data (not ECC), +// for the given version number and error correction level. The result is in the range [9, 2956]. +testable int getNumDataCodewords(int version, enum qrcodegen_Ecc ecl) { + int v = version, e = (int)ecl; + assert(0 <= e && e < 4); + return getNumRawDataModules(v) / 8 + - ECC_CODEWORDS_PER_BLOCK [e][v] + * NUM_ERROR_CORRECTION_BLOCKS[e][v]; +} + + +// Returns the number of data bits that can be stored in a QR Code of the given version number, after +// all function modules are excluded. This includes remainder bits, so it might not be a multiple of 8. +// The result is in the range [208, 29648]. This could be implemented as a 40-entry lookup table. +testable int getNumRawDataModules(int ver) { + assert(qrcodegen_VERSION_MIN <= ver && ver <= qrcodegen_VERSION_MAX); + int result = (16 * ver + 128) * ver + 64; + if (ver >= 2) { + int numAlign = ver / 7 + 2; + result -= (25 * numAlign - 10) * numAlign - 55; + if (ver >= 7) + result -= 36; + } + assert(208 <= result && result <= 29648); + return result; +} + + + +/*---- Reed-Solomon ECC generator functions ----*/ + +// Computes a Reed-Solomon ECC generator polynomial for the given degree, storing in result[0 : degree]. +// This could be implemented as a lookup table over all possible parameter values, instead of as an algorithm. +testable void reedSolomonComputeDivisor(int degree, uint8_t result[]) { + assert(1 <= degree && degree <= qrcodegen_REED_SOLOMON_DEGREE_MAX); + // Polynomial coefficients are stored from highest to lowest power, excluding the leading term which is always 1. + // For example the polynomial x^3 + 255x^2 + 8x + 93 is stored as the uint8 array {255, 8, 93}. + memset(result, 0, (size_t)degree * sizeof(result[0])); + result[degree - 1] = 1; // Start off with the monomial x^0 + + // Compute the product polynomial (x - r^0) * (x - r^1) * (x - r^2) * ... * (x - r^{degree-1}), + // drop the highest monomial term which is always 1x^degree. + // Note that r = 0x02, which is a generator element of this field GF(2^8/0x11D). + uint8_t root = 1; + for (int i = 0; i < degree; i++) { + // Multiply the current product by (x - r^i) + for (int j = 0; j < degree; j++) { + result[j] = reedSolomonMultiply(result[j], root); + if (j + 1 < degree) + result[j] ^= result[j + 1]; + } + root = reedSolomonMultiply(root, 0x02); + } +} + + +// Computes the Reed-Solomon error correction codeword for the given data and divisor polynomials. +// The remainder when data[0 : dataLen] is divided by divisor[0 : degree] is stored in result[0 : degree]. +// All polynomials are in big endian, and the generator has an implicit leading 1 term. +testable void reedSolomonComputeRemainder(const uint8_t data[], int dataLen, + const uint8_t generator[], int degree, uint8_t result[]) { + assert(1 <= degree && degree <= qrcodegen_REED_SOLOMON_DEGREE_MAX); + memset(result, 0, (size_t)degree * sizeof(result[0])); + for (int i = 0; i < dataLen; i++) { // Polynomial division + uint8_t factor = data[i] ^ result[0]; + memmove(&result[0], &result[1], (size_t)(degree - 1) * sizeof(result[0])); + result[degree - 1] = 0; + for (int j = 0; j < degree; j++) + result[j] ^= reedSolomonMultiply(generator[j], factor); + } +} + +#undef qrcodegen_REED_SOLOMON_DEGREE_MAX + + +// Returns the product of the two given field elements modulo GF(2^8/0x11D). +// All inputs are valid. This could be implemented as a 256*256 lookup table. +testable uint8_t reedSolomonMultiply(uint8_t x, uint8_t y) { + // Russian peasant multiplication + uint8_t z = 0; + for (int i = 7; i >= 0; i--) { + z = (uint8_t)((z << 1) ^ ((z >> 7) * 0x11D)); + z ^= ((y >> i) & 1) * x; + } + return z; +} + + + +/*---- Drawing function modules ----*/ + +// Clears the given QR Code grid with light modules for the given +// version's size, then marks every function module as dark. +testable void initializeFunctionModules(int version, uint8_t qrcode[]) { + // Initialize QR Code + int qrsize = version * 4 + 17; + memset(qrcode, 0, (size_t)((qrsize * qrsize + 7) / 8 + 1) * sizeof(qrcode[0])); + qrcode[0] = (uint8_t)qrsize; + + // Fill horizontal and vertical timing patterns + fillRectangle(6, 0, 1, qrsize, qrcode); + fillRectangle(0, 6, qrsize, 1, qrcode); + + // Fill 3 finder patterns (all corners except bottom right) and format bits + fillRectangle(0, 0, 9, 9, qrcode); + fillRectangle(qrsize - 8, 0, 8, 9, qrcode); + fillRectangle(0, qrsize - 8, 9, 8, qrcode); + + // Fill numerous alignment patterns + uint8_t alignPatPos[7]; + int numAlign = getAlignmentPatternPositions(version, alignPatPos); + for (int i = 0; i < numAlign; i++) { + for (int j = 0; j < numAlign; j++) { + // Don't draw on the three finder corners + if (!((i == 0 && j == 0) || (i == 0 && j == numAlign - 1) || (i == numAlign - 1 && j == 0))) + fillRectangle(alignPatPos[i] - 2, alignPatPos[j] - 2, 5, 5, qrcode); + } + } + + // Fill version blocks + if (version >= 7) { + fillRectangle(qrsize - 11, 0, 3, 6, qrcode); + fillRectangle(0, qrsize - 11, 6, 3, qrcode); + } +} + + +// Draws light function modules and possibly some dark modules onto the given QR Code, without changing +// non-function modules. This does not draw the format bits. This requires all function modules to be previously +// marked dark (namely by initializeFunctionModules()), because this may skip redrawing dark function modules. +static void drawLightFunctionModules(uint8_t qrcode[], int version) { + // Draw horizontal and vertical timing patterns + int qrsize = qrcodegen_getSize(qrcode); + for (int i = 7; i < qrsize - 7; i += 2) { + setModuleBounded(qrcode, 6, i, false); + setModuleBounded(qrcode, i, 6, false); + } + + // Draw 3 finder patterns (all corners except bottom right; overwrites some timing modules) + for (int dy = -4; dy <= 4; dy++) { + for (int dx = -4; dx <= 4; dx++) { + int dist = abs(dx); + if (abs(dy) > dist) + dist = abs(dy); + if (dist == 2 || dist == 4) { + setModuleUnbounded(qrcode, 3 + dx, 3 + dy, false); + setModuleUnbounded(qrcode, qrsize - 4 + dx, 3 + dy, false); + setModuleUnbounded(qrcode, 3 + dx, qrsize - 4 + dy, false); + } + } + } + + // Draw numerous alignment patterns + uint8_t alignPatPos[7]; + int numAlign = getAlignmentPatternPositions(version, alignPatPos); + for (int i = 0; i < numAlign; i++) { + for (int j = 0; j < numAlign; j++) { + if ((i == 0 && j == 0) || (i == 0 && j == numAlign - 1) || (i == numAlign - 1 && j == 0)) + continue; // Don't draw on the three finder corners + for (int dy = -1; dy <= 1; dy++) { + for (int dx = -1; dx <= 1; dx++) + setModuleBounded(qrcode, alignPatPos[i] + dx, alignPatPos[j] + dy, dx == 0 && dy == 0); + } + } + } + + // Draw version blocks + if (version >= 7) { + // Calculate error correction code and pack bits + int rem = version; // version is uint6, in the range [7, 40] + for (int i = 0; i < 12; i++) + rem = (rem << 1) ^ ((rem >> 11) * 0x1F25); + long bits = (long)version << 12 | rem; // uint18 + assert(bits >> 18 == 0); + + // Draw two copies + for (int i = 0; i < 6; i++) { + for (int j = 0; j < 3; j++) { + int k = qrsize - 11 + j; + setModuleBounded(qrcode, k, i, (bits & 1) != 0); + setModuleBounded(qrcode, i, k, (bits & 1) != 0); + bits >>= 1; + } + } + } +} + + +// Draws two copies of the format bits (with its own error correction code) based +// on the given mask and error correction level. This always draws all modules of +// the format bits, unlike drawLightFunctionModules() which might skip dark modules. +static void drawFormatBits(enum qrcodegen_Ecc ecl, enum qrcodegen_Mask mask, uint8_t qrcode[]) { + // Calculate error correction code and pack bits + assert(0 <= (int)mask && (int)mask <= 7); + static const int table[] = {1, 0, 3, 2}; + int data = table[(int)ecl] << 3 | (int)mask; // errCorrLvl is uint2, mask is uint3 + int rem = data; + for (int i = 0; i < 10; i++) + rem = (rem << 1) ^ ((rem >> 9) * 0x537); + int bits = (data << 10 | rem) ^ 0x5412; // uint15 + assert(bits >> 15 == 0); + + // Draw first copy + for (int i = 0; i <= 5; i++) + setModuleBounded(qrcode, 8, i, getBit(bits, i)); + setModuleBounded(qrcode, 8, 7, getBit(bits, 6)); + setModuleBounded(qrcode, 8, 8, getBit(bits, 7)); + setModuleBounded(qrcode, 7, 8, getBit(bits, 8)); + for (int i = 9; i < 15; i++) + setModuleBounded(qrcode, 14 - i, 8, getBit(bits, i)); + + // Draw second copy + int qrsize = qrcodegen_getSize(qrcode); + for (int i = 0; i < 8; i++) + setModuleBounded(qrcode, qrsize - 1 - i, 8, getBit(bits, i)); + for (int i = 8; i < 15; i++) + setModuleBounded(qrcode, 8, qrsize - 15 + i, getBit(bits, i)); + setModuleBounded(qrcode, 8, qrsize - 8, true); // Always dark +} + + +// Calculates and stores an ascending list of positions of alignment patterns +// for this version number, returning the length of the list (in the range [0,7]). +// Each position is in the range [0,177), and are used on both the x and y axes. +// This could be implemented as lookup table of 40 variable-length lists of unsigned bytes. +testable int getAlignmentPatternPositions(int version, uint8_t result[7]) { + if (version == 1) + return 0; + int numAlign = version / 7 + 2; + int step = (version * 8 + numAlign * 3 + 5) / (numAlign * 4 - 4) * 2; + for (int i = numAlign - 1, pos = version * 4 + 10; i >= 1; i--, pos -= step) + result[i] = (uint8_t)pos; + result[0] = 6; + return numAlign; +} + + +// Sets every module in the range [left : left + width] * [top : top + height] to dark. +static void fillRectangle(int left, int top, int width, int height, uint8_t qrcode[]) { + for (int dy = 0; dy < height; dy++) { + for (int dx = 0; dx < width; dx++) + setModuleBounded(qrcode, left + dx, top + dy, true); + } +} + + + +/*---- Drawing data modules and masking ----*/ + +// Draws the raw codewords (including data and ECC) onto the given QR Code. This requires the initial state of +// the QR Code to be dark at function modules and light at codeword modules (including unused remainder bits). +static void drawCodewords(const uint8_t data[], int dataLen, uint8_t qrcode[]) { + int qrsize = qrcodegen_getSize(qrcode); + int i = 0; // Bit index into the data + // Do the funny zigzag scan + for (int right = qrsize - 1; right >= 1; right -= 2) { // Index of right column in each column pair + if (right == 6) + right = 5; + for (int vert = 0; vert < qrsize; vert++) { // Vertical counter + for (int j = 0; j < 2; j++) { + int x = right - j; // Actual x coordinate + bool upward = ((right + 1) & 2) == 0; + int y = upward ? qrsize - 1 - vert : vert; // Actual y coordinate + if (!getModuleBounded(qrcode, x, y) && i < dataLen * 8) { + bool dark = getBit(data[i >> 3], 7 - (i & 7)); + setModuleBounded(qrcode, x, y, dark); + i++; + } + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/light by the constructor and are left unchanged by this method + } + } + } + assert(i == dataLen * 8); +} + + +// XORs the codeword modules in this QR Code with the given mask pattern +// and given pattern of function modules. The codeword bits must be drawn +// before masking. Due to the arithmetic of XOR, calling applyMask() with +// the same mask value a second time will undo the mask. A final well-formed +// QR Code needs exactly one (not zero, two, etc.) mask applied. +static void applyMask(const uint8_t functionModules[], uint8_t qrcode[], enum qrcodegen_Mask mask) { + assert(0 <= (int)mask && (int)mask <= 7); // Disallows qrcodegen_Mask_AUTO + int qrsize = qrcodegen_getSize(qrcode); + for (int y = 0; y < qrsize; y++) { + for (int x = 0; x < qrsize; x++) { + if (getModuleBounded(functionModules, x, y)) + continue; + bool invert; + switch ((int)mask) { + case 0: invert = (x + y) % 2 == 0; break; + case 1: invert = y % 2 == 0; break; + case 2: invert = x % 3 == 0; break; + case 3: invert = (x + y) % 3 == 0; break; + case 4: invert = (x / 3 + y / 2) % 2 == 0; break; + case 5: invert = x * y % 2 + x * y % 3 == 0; break; + case 6: invert = (x * y % 2 + x * y % 3) % 2 == 0; break; + case 7: invert = ((x + y) % 2 + x * y % 3) % 2 == 0; break; + default: assert(false); return; + } + bool val = getModuleBounded(qrcode, x, y); + setModuleBounded(qrcode, x, y, val ^ invert); + } + } +} + + +// Calculates and returns the penalty score based on state of the given QR Code's current modules. +// This is used by the automatic mask choice algorithm to find the mask pattern that yields the lowest score. +static long getPenaltyScore(const uint8_t qrcode[]) { + int qrsize = qrcodegen_getSize(qrcode); + long result = 0; + + // Adjacent modules in row having same color, and finder-like patterns + for (int y = 0; y < qrsize; y++) { + bool runColor = false; + int runX = 0; + int runHistory[7] = {0}; + for (int x = 0; x < qrsize; x++) { + if (getModuleBounded(qrcode, x, y) == runColor) { + runX++; + if (runX == 5) + result += PENALTY_N1; + else if (runX > 5) + result++; + } else { + finderPenaltyAddHistory(runX, runHistory, qrsize); + if (!runColor) + result += finderPenaltyCountPatterns(runHistory, qrsize) * PENALTY_N3; + runColor = getModuleBounded(qrcode, x, y); + runX = 1; + } + } + result += finderPenaltyTerminateAndCount(runColor, runX, runHistory, qrsize) * PENALTY_N3; + } + // Adjacent modules in column having same color, and finder-like patterns + for (int x = 0; x < qrsize; x++) { + bool runColor = false; + int runY = 0; + int runHistory[7] = {0}; + for (int y = 0; y < qrsize; y++) { + if (getModuleBounded(qrcode, x, y) == runColor) { + runY++; + if (runY == 5) + result += PENALTY_N1; + else if (runY > 5) + result++; + } else { + finderPenaltyAddHistory(runY, runHistory, qrsize); + if (!runColor) + result += finderPenaltyCountPatterns(runHistory, qrsize) * PENALTY_N3; + runColor = getModuleBounded(qrcode, x, y); + runY = 1; + } + } + result += finderPenaltyTerminateAndCount(runColor, runY, runHistory, qrsize) * PENALTY_N3; + } + + // 2*2 blocks of modules having same color + for (int y = 0; y < qrsize - 1; y++) { + for (int x = 0; x < qrsize - 1; x++) { + bool color = getModuleBounded(qrcode, x, y); + if ( color == getModuleBounded(qrcode, x + 1, y) && + color == getModuleBounded(qrcode, x, y + 1) && + color == getModuleBounded(qrcode, x + 1, y + 1)) + result += PENALTY_N2; + } + } + + // Balance of dark and light modules + int dark = 0; + for (int y = 0; y < qrsize; y++) { + for (int x = 0; x < qrsize; x++) { + if (getModuleBounded(qrcode, x, y)) + dark++; + } + } + int total = qrsize * qrsize; // Note that size is odd, so dark/total != 1/2 + // Compute the smallest integer k >= 0 such that (45-5k)% <= dark/total <= (55+5k)% + int k = (int)((labs(dark * 20L - total * 10L) + total - 1) / total) - 1; + assert(0 <= k && k <= 9); + result += k * PENALTY_N4; + assert(0 <= result && result <= 2568888L); // Non-tight upper bound based on default values of PENALTY_N1, ..., N4 + return result; +} + + +// Can only be called immediately after a light run is added, and +// returns either 0, 1, or 2. A helper function for getPenaltyScore(). +static int finderPenaltyCountPatterns(const int runHistory[7], int qrsize) { + int n = runHistory[1]; + assert(n <= qrsize * 3); (void)qrsize; + bool core = n > 0 && runHistory[2] == n && runHistory[3] == n * 3 && runHistory[4] == n && runHistory[5] == n; + // The maximum QR Code size is 177, hence the dark run length n <= 177. + // Arithmetic is promoted to int, so n*4 will not overflow. + return (core && runHistory[0] >= n * 4 && runHistory[6] >= n ? 1 : 0) + + (core && runHistory[6] >= n * 4 && runHistory[0] >= n ? 1 : 0); +} + + +// Must be called at the end of a line (row or column) of modules. A helper function for getPenaltyScore(). +static int finderPenaltyTerminateAndCount(bool currentRunColor, int currentRunLength, int runHistory[7], int qrsize) { + if (currentRunColor) { // Terminate dark run + finderPenaltyAddHistory(currentRunLength, runHistory, qrsize); + currentRunLength = 0; + } + currentRunLength += qrsize; // Add light border to final run + finderPenaltyAddHistory(currentRunLength, runHistory, qrsize); + return finderPenaltyCountPatterns(runHistory, qrsize); +} + + +// Pushes the given value to the front and drops the last value. A helper function for getPenaltyScore(). +static void finderPenaltyAddHistory(int currentRunLength, int runHistory[7], int qrsize) { + if (runHistory[0] == 0) + currentRunLength += qrsize; // Add light border to initial run + memmove(&runHistory[1], &runHistory[0], 6 * sizeof(runHistory[0])); + runHistory[0] = currentRunLength; +} + + + +/*---- Basic QR Code information ----*/ + +// Public function - see documentation comment in header file. +int qrcodegen_getSize(const uint8_t qrcode[]) { + assert(qrcode != NULL); + int result = qrcode[0]; + assert((qrcodegen_VERSION_MIN * 4 + 17) <= result + && result <= (qrcodegen_VERSION_MAX * 4 + 17)); + return result; +} + + +// Public function - see documentation comment in header file. +bool qrcodegen_getModule(const uint8_t qrcode[], int x, int y) { + assert(qrcode != NULL); + int qrsize = qrcode[0]; + return (0 <= x && x < qrsize && 0 <= y && y < qrsize) && getModuleBounded(qrcode, x, y); +} + + +// Returns the color of the module at the given coordinates, which must be in bounds. +testable bool getModuleBounded(const uint8_t qrcode[], int x, int y) { + int qrsize = qrcode[0]; + assert(21 <= qrsize && qrsize <= 177 && 0 <= x && x < qrsize && 0 <= y && y < qrsize); + int index = y * qrsize + x; + return getBit(qrcode[(index >> 3) + 1], index & 7); +} + + +// Sets the color of the module at the given coordinates, which must be in bounds. +testable void setModuleBounded(uint8_t qrcode[], int x, int y, bool isDark) { + int qrsize = qrcode[0]; + assert(21 <= qrsize && qrsize <= 177 && 0 <= x && x < qrsize && 0 <= y && y < qrsize); + int index = y * qrsize + x; + int bitIndex = index & 7; + int byteIndex = (index >> 3) + 1; + if (isDark) + qrcode[byteIndex] |= 1 << bitIndex; + else + qrcode[byteIndex] &= (1 << bitIndex) ^ 0xFF; +} + + +// Sets the color of the module at the given coordinates, doing nothing if out of bounds. +testable void setModuleUnbounded(uint8_t qrcode[], int x, int y, bool isDark) { + int qrsize = qrcode[0]; + if (0 <= x && x < qrsize && 0 <= y && y < qrsize) + setModuleBounded(qrcode, x, y, isDark); +} + + +// Returns true iff the i'th bit of x is set to 1. Requires x >= 0 and 0 <= i <= 14. +static bool getBit(int x, int i) { + return ((x >> i) & 1) != 0; +} + + + +/*---- Segment handling ----*/ + +// Public function - see documentation comment in header file. +bool qrcodegen_isNumeric(const char *text) { + assert(text != NULL); + for (; *text != '\0'; text++) { + if (*text < '0' || *text > '9') + return false; + } + return true; +} + + +// Public function - see documentation comment in header file. +bool qrcodegen_isAlphanumeric(const char *text) { + assert(text != NULL); + for (; *text != '\0'; text++) { + if (strchr(ALPHANUMERIC_CHARSET, *text) == NULL) + return false; + } + return true; +} + + +// Public function - see documentation comment in header file. +size_t qrcodegen_calcSegmentBufferSize(enum qrcodegen_Mode mode, size_t numChars) { + int temp = calcSegmentBitLength(mode, numChars); + if (temp == LENGTH_OVERFLOW) + return SIZE_MAX; + assert(0 <= temp && temp <= INT16_MAX); + return ((size_t)temp + 7) / 8; +} + + +// Returns the number of data bits needed to represent a segment +// containing the given number of characters using the given mode. Notes: +// - Returns LENGTH_OVERFLOW on failure, i.e. numChars > INT16_MAX +// or the number of needed bits exceeds INT16_MAX (i.e. 32767). +// - Otherwise, all valid results are in the range [0, INT16_MAX]. +// - For byte mode, numChars measures the number of bytes, not Unicode code points. +// - For ECI mode, numChars must be 0, and the worst-case number of bits is returned. +// An actual ECI segment can have shorter data. For non-ECI modes, the result is exact. +testable int calcSegmentBitLength(enum qrcodegen_Mode mode, size_t numChars) { + // All calculations are designed to avoid overflow on all platforms + if (numChars > (unsigned int)INT16_MAX) + return LENGTH_OVERFLOW; + long result = (long)numChars; + if (mode == qrcodegen_Mode_NUMERIC) + result = (result * 10 + 2) / 3; // ceil(10/3 * n) + else if (mode == qrcodegen_Mode_ALPHANUMERIC) + result = (result * 11 + 1) / 2; // ceil(11/2 * n) + else if (mode == qrcodegen_Mode_BYTE) + result *= 8; + else if (mode == qrcodegen_Mode_KANJI) + result *= 13; + else if (mode == qrcodegen_Mode_ECI && numChars == 0) + result = 3 * 8; + else { // Invalid argument + assert(false); + return LENGTH_OVERFLOW; + } + assert(result >= 0); + if (result > INT16_MAX) + return LENGTH_OVERFLOW; + return (int)result; +} + + +// Public function - see documentation comment in header file. +struct qrcodegen_Segment qrcodegen_makeBytes(const uint8_t data[], size_t len, uint8_t buf[]) { + assert(data != NULL || len == 0); + struct qrcodegen_Segment result; + result.mode = qrcodegen_Mode_BYTE; + result.bitLength = calcSegmentBitLength(result.mode, len); + assert(result.bitLength != LENGTH_OVERFLOW); + result.numChars = (int)len; + if (len > 0) + memcpy(buf, data, len * sizeof(buf[0])); + result.data = buf; + return result; +} + + +// Public function - see documentation comment in header file. +struct qrcodegen_Segment qrcodegen_makeNumeric(const char *digits, uint8_t buf[]) { + assert(digits != NULL); + struct qrcodegen_Segment result; + size_t len = strlen(digits); + result.mode = qrcodegen_Mode_NUMERIC; + int bitLen = calcSegmentBitLength(result.mode, len); + assert(bitLen != LENGTH_OVERFLOW); + result.numChars = (int)len; + if (bitLen > 0) + memset(buf, 0, ((size_t)bitLen + 7) / 8 * sizeof(buf[0])); + result.bitLength = 0; + + unsigned int accumData = 0; + int accumCount = 0; + for (; *digits != '\0'; digits++) { + char c = *digits; + assert('0' <= c && c <= '9'); + accumData = accumData * 10 + (unsigned int)(c - '0'); + accumCount++; + if (accumCount == 3) { + appendBitsToBuffer(accumData, 10, buf, &result.bitLength); + accumData = 0; + accumCount = 0; + } + } + if (accumCount > 0) // 1 or 2 digits remaining + appendBitsToBuffer(accumData, accumCount * 3 + 1, buf, &result.bitLength); + assert(result.bitLength == bitLen); + result.data = buf; + return result; +} + + +// Public function - see documentation comment in header file. +struct qrcodegen_Segment qrcodegen_makeAlphanumeric(const char *text, uint8_t buf[]) { + assert(text != NULL); + struct qrcodegen_Segment result; + size_t len = strlen(text); + result.mode = qrcodegen_Mode_ALPHANUMERIC; + int bitLen = calcSegmentBitLength(result.mode, len); + assert(bitLen != LENGTH_OVERFLOW); + result.numChars = (int)len; + if (bitLen > 0) + memset(buf, 0, ((size_t)bitLen + 7) / 8 * sizeof(buf[0])); + result.bitLength = 0; + + unsigned int accumData = 0; + int accumCount = 0; + for (; *text != '\0'; text++) { + const char *temp = strchr(ALPHANUMERIC_CHARSET, *text); + assert(temp != NULL); + accumData = accumData * 45 + (unsigned int)(temp - ALPHANUMERIC_CHARSET); + accumCount++; + if (accumCount == 2) { + appendBitsToBuffer(accumData, 11, buf, &result.bitLength); + accumData = 0; + accumCount = 0; + } + } + if (accumCount > 0) // 1 character remaining + appendBitsToBuffer(accumData, 6, buf, &result.bitLength); + assert(result.bitLength == bitLen); + result.data = buf; + return result; +} + + +// Public function - see documentation comment in header file. +struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]) { + struct qrcodegen_Segment result; + result.mode = qrcodegen_Mode_ECI; + result.numChars = 0; + result.bitLength = 0; + if (assignVal < 0) + assert(false); + else if (assignVal < (1 << 7)) { + memset(buf, 0, 1 * sizeof(buf[0])); + appendBitsToBuffer((unsigned int)assignVal, 8, buf, &result.bitLength); + } else if (assignVal < (1 << 14)) { + memset(buf, 0, 2 * sizeof(buf[0])); + appendBitsToBuffer(2, 2, buf, &result.bitLength); + appendBitsToBuffer((unsigned int)assignVal, 14, buf, &result.bitLength); + } else if (assignVal < 1000000L) { + memset(buf, 0, 3 * sizeof(buf[0])); + appendBitsToBuffer(6, 3, buf, &result.bitLength); + appendBitsToBuffer((unsigned int)(assignVal >> 10), 11, buf, &result.bitLength); + appendBitsToBuffer((unsigned int)(assignVal & 0x3FF), 10, buf, &result.bitLength); + } else + assert(false); + result.data = buf; + return result; +} + + +// Calculates the number of bits needed to encode the given segments at the given version. +// Returns a non-negative number if successful. Otherwise returns LENGTH_OVERFLOW if a segment +// has too many characters to fit its length field, or the total bits exceeds INT16_MAX. +testable int getTotalBits(const struct qrcodegen_Segment segs[], size_t len, int version) { + assert(segs != NULL || len == 0); + long result = 0; + for (size_t i = 0; i < len; i++) { + int numChars = segs[i].numChars; + int bitLength = segs[i].bitLength; + assert(0 <= numChars && numChars <= INT16_MAX); + assert(0 <= bitLength && bitLength <= INT16_MAX); + int ccbits = numCharCountBits(segs[i].mode, version); + assert(0 <= ccbits && ccbits <= 16); + if (numChars >= (1L << ccbits)) + return LENGTH_OVERFLOW; // The segment's length doesn't fit the field's bit width + result += 4L + ccbits + bitLength; + if (result > INT16_MAX) + return LENGTH_OVERFLOW; // The sum might overflow an int type + } + assert(0 <= result && result <= INT16_MAX); + return (int)result; +} + + +// Returns the bit width of the character count field for a segment in the given mode +// in a QR Code at the given version number. The result is in the range [0, 16]. +static int numCharCountBits(enum qrcodegen_Mode mode, int version) { + assert(qrcodegen_VERSION_MIN <= version && version <= qrcodegen_VERSION_MAX); + int i = (version + 7) / 17; + switch (mode) { + case qrcodegen_Mode_NUMERIC : { static const int temp[] = {10, 12, 14}; return temp[i]; } + case qrcodegen_Mode_ALPHANUMERIC: { static const int temp[] = { 9, 11, 13}; return temp[i]; } + case qrcodegen_Mode_BYTE : { static const int temp[] = { 8, 16, 16}; return temp[i]; } + case qrcodegen_Mode_KANJI : { static const int temp[] = { 8, 10, 12}; return temp[i]; } + case qrcodegen_Mode_ECI : return 0; + default: assert(false); return -1; // Dummy value + } +} + + +#undef LENGTH_OVERFLOW diff --git a/components/domain/third_party/qrcodegen.h b/components/domain/third_party/qrcodegen.h new file mode 100644 index 0000000..6bbc157 --- /dev/null +++ b/components/domain/third_party/qrcodegen.h @@ -0,0 +1,385 @@ +/* + * QR Code generator library (C) + * + * Copyright (c) Project Nayuki. (MIT License) + * https://www.nayuki.io/page/qr-code-generator-library + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to + * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of + * the Software, and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * - The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * - The Software is provided "as is", without warranty of any kind, express or + * implied, including but not limited to the warranties of merchantability, + * fitness for a particular purpose and noninfringement. In no event shall the + * authors or copyright holders be liable for any claim, damages or other + * liability, whether in an action of contract, tort or otherwise, arising from, + * out of or in connection with the Software or the use or other dealings in the + * Software. + */ + +#pragma once + +#include +#include +#include + + +#ifdef __cplusplus +extern "C" { +#endif + + +/* + * This library creates QR Code symbols, which is a type of two-dimension barcode. + * Invented by Denso Wave and described in the ISO/IEC 18004 standard. + * A QR Code structure is an immutable square grid of dark and light cells. + * The library provides functions to create a QR Code from text or binary data. + * The library covers the QR Code Model 2 specification, supporting all versions (sizes) + * from 1 to 40, all 4 error correction levels, and 4 character encoding modes. + * + * Ways to create a QR Code object: + * - High level: Take the payload data and call qrcodegen_encodeText() or qrcodegen_encodeBinary(). + * - Low level: Custom-make the list of segments and call + * qrcodegen_encodeSegments() or qrcodegen_encodeSegmentsAdvanced(). + * (Note that all ways require supplying the desired error correction level and various byte buffers.) + */ + + +/*---- Enum and struct types----*/ + +/* + * The error correction level in a QR Code symbol. + */ +enum qrcodegen_Ecc { + // Must be declared in ascending order of error protection + // so that an internal qrcodegen function works properly + qrcodegen_Ecc_LOW = 0 , // The QR Code can tolerate about 7% erroneous codewords + qrcodegen_Ecc_MEDIUM , // The QR Code can tolerate about 15% erroneous codewords + qrcodegen_Ecc_QUARTILE, // The QR Code can tolerate about 25% erroneous codewords + qrcodegen_Ecc_HIGH , // The QR Code can tolerate about 30% erroneous codewords +}; + + +/* + * The mask pattern used in a QR Code symbol. + */ +enum qrcodegen_Mask { + // A special value to tell the QR Code encoder to + // automatically select an appropriate mask pattern + qrcodegen_Mask_AUTO = -1, + // The eight actual mask patterns + qrcodegen_Mask_0 = 0, + qrcodegen_Mask_1, + qrcodegen_Mask_2, + qrcodegen_Mask_3, + qrcodegen_Mask_4, + qrcodegen_Mask_5, + qrcodegen_Mask_6, + qrcodegen_Mask_7, +}; + + +/* + * Describes how a segment's data bits are interpreted. + */ +enum qrcodegen_Mode { + qrcodegen_Mode_NUMERIC = 0x1, + qrcodegen_Mode_ALPHANUMERIC = 0x2, + qrcodegen_Mode_BYTE = 0x4, + qrcodegen_Mode_KANJI = 0x8, + qrcodegen_Mode_ECI = 0x7, +}; + + +/* + * A segment of character/binary/control data in a QR Code symbol. + * The mid-level way to create a segment is to take the payload data + * and call a factory function such as qrcodegen_makeNumeric(). + * The low-level way to create a segment is to custom-make the bit buffer + * and initialize a qrcodegen_Segment struct with appropriate values. + * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. + * Any segment longer than this is meaningless for the purpose of generating QR Codes. + * Moreover, the maximum allowed bit length is 32767 because + * the largest QR Code (version 40) has 31329 modules. + */ +struct qrcodegen_Segment { + // The mode indicator of this segment. + enum qrcodegen_Mode mode; + + // The length of this segment's unencoded data. Measured in characters for + // numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode. + // Always zero or positive. Not the same as the data's bit length. + int numChars; + + // The data bits of this segment, packed in bitwise big endian. + // Can be null if the bit length is zero. + uint8_t *data; + + // The number of valid data bits used in the buffer. Requires + // 0 <= bitLength <= 32767, and bitLength <= (capacity of data array) * 8. + // The character count (numChars) must agree with the mode and the bit buffer length. + int bitLength; +}; + + + +/*---- Macro constants and functions ----*/ + +#define qrcodegen_VERSION_MIN 1 // The minimum version number supported in the QR Code Model 2 standard +#define qrcodegen_VERSION_MAX 40 // The maximum version number supported in the QR Code Model 2 standard + +// Calculates the number of bytes needed to store any QR Code up to and including the given version number, +// as a compile-time constant. For example, 'uint8_t buffer[qrcodegen_BUFFER_LEN_FOR_VERSION(25)];' +// can store any single QR Code from version 1 to 25 (inclusive). The result fits in an int (or int16). +// Requires qrcodegen_VERSION_MIN <= n <= qrcodegen_VERSION_MAX. +#define qrcodegen_BUFFER_LEN_FOR_VERSION(n) ((((n) * 4 + 17) * ((n) * 4 + 17) + 7) / 8 + 1) + +// The worst-case number of bytes needed to store one QR Code, up to and including +// version 40. This value equals 3918, which is just under 4 kilobytes. +// Use this more convenient value to avoid calculating tighter memory bounds for buffers. +#define qrcodegen_BUFFER_LEN_MAX qrcodegen_BUFFER_LEN_FOR_VERSION(qrcodegen_VERSION_MAX) + + + +/*---- Functions (high level) to generate QR Codes ----*/ + +/* + * Encodes the given text string to a QR Code, returning true if successful. + * If the data is too long to fit in any version in the given range + * at the given ECC level, then false is returned. + * + * The input text must be encoded in UTF-8 and contain no NULs. + * Requires 1 <= minVersion <= maxVersion <= 40. + * + * The smallest possible QR Code version within the given range is automatically + * chosen for the output. Iff boostEcl is true, then the ECC level of the result + * may be higher than the ecl argument if it can be done without increasing the + * version. The mask is either between qrcodegen_Mask_0 to 7 to force that mask, or + * qrcodegen_Mask_AUTO to automatically choose an appropriate mask (which may be slow). + * + * About the arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion): + * - Before calling the function: + * - The array ranges tempBuffer[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The initial state of both ranges can be uninitialized + * because the function always writes before reading. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - tempBuffer contains no useful data and should be treated as entirely uninitialized. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). + * + * If successful, the resulting QR Code may use numeric, + * alphanumeric, or byte mode to encode the text. + * + * In the most optimistic case, a QR Code at version 40 with low ECC + * can hold any UTF-8 string up to 2953 bytes, or any alphanumeric string + * up to 4296 characters, or any digit string up to 7089 characters. + * These numbers represent the hard upper limit of the QR Code standard. + * + * Please consult the QR Code specification for information on + * data capacities per version, ECC level, and text encoding mode. + */ +bool qrcodegen_encodeText(const char *text, uint8_t tempBuffer[], uint8_t qrcode[], + enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl); + + +/* + * Encodes the given binary data to a QR Code, returning true if successful. + * If the data is too long to fit in any version in the given range + * at the given ECC level, then false is returned. + * + * Requires 1 <= minVersion <= maxVersion <= 40. + * + * The smallest possible QR Code version within the given range is automatically + * chosen for the output. Iff boostEcl is true, then the ECC level of the result + * may be higher than the ecl argument if it can be done without increasing the + * version. The mask is either between qrcodegen_Mask_0 to 7 to force that mask, or + * qrcodegen_Mask_AUTO to automatically choose an appropriate mask (which may be slow). + * + * About the arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(maxVersion): + * - Before calling the function: + * - The array ranges dataAndTemp[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The input array range dataAndTemp[0 : dataLen] should normally be + * valid UTF-8 text, but is not required by the QR Code standard. + * - The initial state of dataAndTemp[dataLen : len] and qrcode[0 : len] + * can be uninitialized because the function always writes before reading. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - dataAndTemp contains no useful data and should be treated as entirely uninitialized. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). + * + * If successful, the resulting QR Code will use byte mode to encode the data. + * + * In the most optimistic case, a QR Code at version 40 with low ECC can hold any byte + * sequence up to length 2953. This is the hard upper limit of the QR Code standard. + * + * Please consult the QR Code specification for information on + * data capacities per version, ECC level, and text encoding mode. + */ +bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcode[], + enum qrcodegen_Ecc ecl, int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl); + + +/*---- Functions (low level) to generate QR Codes ----*/ + +/* + * Encodes the given segments to a QR Code, returning true if successful. + * If the data is too long to fit in any version at the given ECC level, + * then false is returned. + * + * The smallest possible QR Code version is automatically chosen for + * the output. The ECC level of the result may be higher than the + * ecl argument if it can be done without increasing the version. + * + * About the byte arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(qrcodegen_VERSION_MAX): + * - Before calling the function: + * - The array ranges tempBuffer[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The initial state of both ranges can be uninitialized + * because the function always writes before reading. + * - The input array segs can contain segments whose data buffers overlap with tempBuffer. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - tempBuffer contains no useful data and should be treated as entirely uninitialized. + * - Any segment whose data buffer overlaps with tempBuffer[0 : len] + * must be treated as having invalid values in that array. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). + * + * Please consult the QR Code specification for information on + * data capacities per version, ECC level, and text encoding mode. + * + * This function allows the user to create a custom sequence of segments that switches + * between modes (such as alphanumeric and byte) to encode text in less space. + * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary(). + */ +bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len, + enum qrcodegen_Ecc ecl, uint8_t tempBuffer[], uint8_t qrcode[]); + + +/* + * Encodes the given segments to a QR Code, returning true if successful. + * If the data is too long to fit in any version in the given range + * at the given ECC level, then false is returned. + * + * Requires 1 <= minVersion <= maxVersion <= 40. + * + * The smallest possible QR Code version within the given range is automatically + * chosen for the output. Iff boostEcl is true, then the ECC level of the result + * may be higher than the ecl argument if it can be done without increasing the + * version. The mask is either between qrcodegen_Mask_0 to 7 to force that mask, or + * qrcodegen_Mask_AUTO to automatically choose an appropriate mask (which may be slow). + * + * About the byte arrays, letting len = qrcodegen_BUFFER_LEN_FOR_VERSION(qrcodegen_VERSION_MAX): + * - Before calling the function: + * - The array ranges tempBuffer[0 : len] and qrcode[0 : len] must allow + * reading and writing; hence each array must have a length of at least len. + * - The two ranges must not overlap (aliasing). + * - The initial state of both ranges can be uninitialized + * because the function always writes before reading. + * - The input array segs can contain segments whose data buffers overlap with tempBuffer. + * - After the function returns: + * - Both ranges have no guarantee on which elements are initialized and what values are stored. + * - tempBuffer contains no useful data and should be treated as entirely uninitialized. + * - Any segment whose data buffer overlaps with tempBuffer[0 : len] + * must be treated as having invalid values in that array. + * - If successful, qrcode can be passed into qrcodegen_getSize() and qrcodegen_getModule(). + * + * Please consult the QR Code specification for information on + * data capacities per version, ECC level, and text encoding mode. + * + * This function allows the user to create a custom sequence of segments that switches + * between modes (such as alphanumeric and byte) to encode text in less space. + * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary(). + */ +bool qrcodegen_encodeSegmentsAdvanced(const struct qrcodegen_Segment segs[], size_t len, enum qrcodegen_Ecc ecl, + int minVersion, int maxVersion, enum qrcodegen_Mask mask, bool boostEcl, uint8_t tempBuffer[], uint8_t qrcode[]); + + +/* + * Tests whether the given string can be encoded as a segment in numeric mode. + * A string is encodable iff each character is in the range 0 to 9. + */ +bool qrcodegen_isNumeric(const char *text); + + +/* + * Tests whether the given string can be encoded as a segment in alphanumeric mode. + * A string is encodable iff each character is in the following set: 0 to 9, A to Z + * (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon. + */ +bool qrcodegen_isAlphanumeric(const char *text); + + +/* + * Returns the number of bytes (uint8_t) needed for the data buffer of a segment + * containing the given number of characters using the given mode. Notes: + * - Returns SIZE_MAX on failure, i.e. numChars > INT16_MAX or the internal + * calculation of the number of needed bits exceeds INT16_MAX (i.e. 32767). + * - Otherwise, all valid results are in the range [0, ceil(INT16_MAX / 8)], i.e. at most 4096. + * - It is okay for the user to allocate more bytes for the buffer than needed. + * - For byte mode, numChars measures the number of bytes, not Unicode code points. + * - For ECI mode, numChars must be 0, and the worst-case number of bytes is returned. + * An actual ECI segment can have shorter data. For non-ECI modes, the result is exact. + */ +size_t qrcodegen_calcSegmentBufferSize(enum qrcodegen_Mode mode, size_t numChars); + + +/* + * Returns a segment representing the given binary data encoded in + * byte mode. All input byte arrays are acceptable. Any text string + * can be converted to UTF-8 bytes and encoded as a byte mode segment. + */ +struct qrcodegen_Segment qrcodegen_makeBytes(const uint8_t data[], size_t len, uint8_t buf[]); + + +/* + * Returns a segment representing the given string of decimal digits encoded in numeric mode. + */ +struct qrcodegen_Segment qrcodegen_makeNumeric(const char *digits, uint8_t buf[]); + + +/* + * Returns a segment representing the given text string encoded in alphanumeric mode. + * The characters allowed are: 0 to 9, A to Z (uppercase only), space, + * dollar, percent, asterisk, plus, hyphen, period, slash, colon. + */ +struct qrcodegen_Segment qrcodegen_makeAlphanumeric(const char *text, uint8_t buf[]); + + +/* + * Returns a segment representing an Extended Channel Interpretation + * (ECI) designator with the given assignment value. + */ +struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]); + + +/*---- Functions to extract raw data from QR Codes ----*/ + +/* + * Returns the side length of the given QR Code, assuming that encoding succeeded. + * The result is in the range [21, 177]. Note that the length of the array buffer + * is related to the side length - every 'uint8_t qrcode[]' must have length at least + * qrcodegen_BUFFER_LEN_FOR_VERSION(version), which equals ceil(size^2 / 8 + 1). + */ +int qrcodegen_getSize(const uint8_t qrcode[]); + + +/* + * Returns the color of the module (pixel) at the given coordinates, which is false + * for light or true for dark. The top left corner has the coordinates (x=0, y=0). + * If the given coordinates are out of bounds, then false (light) is returned. + */ +bool qrcodegen_getModule(const uint8_t qrcode[], int x, int y); + + +#ifdef __cplusplus +} +#endif diff --git a/components/platform/CMakeLists.txt b/components/platform/CMakeLists.txt new file mode 100644 index 0000000..a9d6d02 --- /dev/null +++ b/components/platform/CMakeLists.txt @@ -0,0 +1,36 @@ +idf_component_register( + SRCS + "src/platform_bootstrap.c" + "src/wifi_manager.c" + "src/ble_printer_client.c" + "src/direct_thermal_printer.c" + "src/display_st7789.c" + "src/display_lcd_module.c" + "src/display_lcd_decode_image.c" + "src/display_st7789p3.c" + "src/voice_audio.c" + "src/runtime_policy.c" + "src/runtime_diagnostics.c" + INCLUDE_DIRS + "include" + PRIV_INCLUDE_DIRS + "internal" + REQUIRES + bt + esp_coex + esp_wifi + esp_netif + esp_event + nvs_flash + mbedtls + esp_adc + esp_driver_gpio + esp_driver_spi + lvgl + espressif__libpng + esp_codec_dev + esp_audio_codec + driver + EMBED_FILES + "assets/lcd_demo.png" +) diff --git a/components/platform/README.md b/components/platform/README.md new file mode 100644 index 0000000..b571305 --- /dev/null +++ b/components/platform/README.md @@ -0,0 +1,13 @@ +# Platform Layer + +Purpose: hardware and system resource abstraction only. + +Allowed examples: +- Wi-Fi/BLE driver wrappers +- NVS/time/RTOS/system adapters +- board-specific IO and transport bindings + +Rules: +- Expose stable APIs in `include/`. +- Keep private headers in `internal/`. +- Do not depend on `domain`, `control_plane`, or `app_composition`. diff --git a/components/platform/assets/lcd_demo.png b/components/platform/assets/lcd_demo.png new file mode 100644 index 0000000000000000000000000000000000000000..5f481b05ceee7db3047afcea4570c424e1c8743a GIT binary patch literal 187043 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

    &BzD17BfI5TrL4IWwJ{1>Hqwz60n(CwDEt!T9f4 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 +#include +#include + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +// ---------- platform_bootstrap ---------- +esp_err_t platform_bootstrap_init(void); + +// ---------- wifi_manager ---------- +esp_err_t wifi_manager_start(void); +esp_err_t wifi_manager_stop(void); + +bool wifi_manager_is_ready(void); +void wifi_manager_get_ip(char *buf, size_t buf_len); + +// ---------- ble_printer_client ---------- +typedef void (*ble_frame_rx_cb_t)(const uint8_t *data, size_t len); + +typedef struct { + bool connected; + bool notify_ready; + uint16_t mtu; +} ble_link_state_t; + +esp_err_t ble_printer_client_init(ble_frame_rx_cb_t rx_cb); +esp_err_t ble_printer_client_connect(const char *target_name, uint32_t timeout_ms); +void ble_printer_client_disconnect(void); + +bool ble_printer_client_is_connected(void); +void ble_printer_client_get_link_state(ble_link_state_t *out_state); +esp_err_t ble_printer_client_write(const uint8_t *data, size_t len); + +// ---------- direct_thermal_printer ---------- +typedef struct { + bool has_paper; + int8_t paper_gpio_level; + uint8_t paper_present_level; + uint8_t battery_percent; + float temperature_c; + int64_t updated_ms; +} platform_printer_sensors_t; + +typedef struct { + uint16_t width; + uint16_t height; + const uint8_t *raster; + size_t raster_len; + uint16_t strobe_on_time_us; + uint16_t strobe_interval_us; + uint16_t motor_step_delay_us; + uint8_t motor_steps_per_line; + uint32_t timeout_ms; + bool ignore_precheck; + const volatile bool *cancel_flag; +} platform_direct_print_request_t; + +esp_err_t platform_direct_printer_init(void); +void platform_direct_printer_deinit(void); +esp_err_t platform_direct_printer_connect(uint32_t timeout_ms); +void platform_direct_printer_disconnect(void); +bool platform_direct_printer_is_connected(void); +esp_err_t platform_direct_printer_get_sensors(platform_printer_sensors_t *out_sensors); +esp_err_t platform_direct_printer_get_debug_config(uint16_t *out_shift_clock_high_us, + uint16_t *out_shift_clock_low_us, + uint16_t *out_latch_pulse_us, + bool *out_strobe_active_high, + bool *out_boost_active_high, + uint16_t *out_override_strobe_on_us, + uint16_t *out_override_strobe_interval_us, + uint16_t *out_override_motor_step_us, + uint8_t *out_override_steps_per_line); +esp_err_t platform_direct_printer_set_debug_config(bool has_config, + uint16_t shift_clock_high_us, + uint16_t shift_clock_low_us, + uint16_t latch_pulse_us, + bool strobe_active_high, + bool boost_active_high, + uint16_t override_strobe_on_us, + uint16_t override_strobe_interval_us, + uint16_t override_motor_step_us, + uint8_t override_steps_per_line, + bool reset_defaults, + char *err, + size_t err_len); +esp_err_t platform_direct_printer_print(const platform_direct_print_request_t *request, + char *err, + size_t err_len); +esp_err_t platform_direct_printer_gap_move(uint32_t timeout_ms, char *err, size_t err_len); + +// ---------- display_st7789 ---------- +esp_err_t platform_display_init(void); +esp_err_t platform_display_show_test_pattern(void); +esp_err_t platform_display_show_raster_1bpp(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len); +esp_err_t platform_display_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len); +void platform_display_mark_shared_spi_dirty(void); +void platform_display_deinit(void); + +// ---------- voice_audio ---------- +typedef struct { + uint32_t sample_rate; + uint8_t channels; + uint8_t bits_per_sample; + int output_volume; + float input_gain_db; +} voice_audio_open_config_t; + +esp_err_t voice_audio_open(const voice_audio_open_config_t *cfg, char *err, size_t err_len); +void voice_audio_close(void); + +bool voice_audio_is_open(void); + +// timeout_ms applies to voice-audio mutex acquisition. +// Underlying codec driver I/O duration depends on driver/clocking state. +esp_err_t voice_audio_read_pcm(int16_t *pcm, + size_t samples, + uint32_t timeout_ms, + char *err, + size_t err_len); +// timeout_ms applies to voice-audio mutex acquisition. +// Underlying codec driver I/O duration depends on driver/clocking state. +esp_err_t voice_audio_write_pcm(const int16_t *pcm, + size_t samples, + uint32_t timeout_ms, + char *err, + size_t err_len); + +// ---------- runtime_policy ---------- +uint32_t runtime_policy_wifi_connect_timeout_ms(void); + +uint32_t runtime_policy_lifecycle_start_retry_count(void); +uint32_t runtime_policy_lifecycle_retry_backoff_ms(uint32_t attempt); +bool runtime_policy_is_retryable_error(esp_err_t err); + +uint32_t runtime_policy_printer_control_lock_timeout_ms(void); +uint32_t runtime_policy_printer_worker_queue_wait_ms(void); +uint32_t runtime_policy_printer_queue_retry_delay_ms(void); +uint32_t runtime_policy_printer_status_poll_interval_ms(void); +uint32_t runtime_policy_printer_stop_timeout_ms(void); +uint8_t runtime_policy_printer_default_backend(void); + +bool runtime_policy_direct_printer_enabled(void); +uint32_t runtime_policy_direct_printer_operation_timeout_ms(void); +uint16_t runtime_policy_direct_printer_strobe_on_us(void); +uint16_t runtime_policy_direct_printer_strobe_interval_us(void); +uint16_t runtime_policy_direct_printer_motor_step_us(void); +bool runtime_policy_direct_printer_motor_reverse(void); +uint8_t runtime_policy_direct_printer_steps_per_line(void); +uint16_t runtime_policy_direct_printer_gap_steps(void); +float runtime_policy_direct_printer_temp_min_c(void); +float runtime_policy_direct_printer_temp_max_c(void); +uint8_t runtime_policy_direct_printer_battery_min_percent(void); +uint8_t runtime_policy_direct_printer_paper_present_level(void); +uint16_t runtime_policy_direct_printer_battery_empty_mv(void); +uint16_t runtime_policy_direct_printer_battery_full_mv(void); +uint16_t runtime_policy_direct_printer_battery_divider_ratio_x1000(void); +uint32_t runtime_policy_direct_printer_ntc_pullup_ohms(void); +uint32_t runtime_policy_direct_printer_ntc_r25_ohms(void); +uint32_t runtime_policy_direct_printer_ntc_beta(void); + +uint32_t runtime_policy_rest_printer_connect_timeout_ms(void); +uint32_t runtime_policy_rest_label_timeout_ms(void); +uint32_t runtime_policy_rest_ota_timeout_ms(void); + +uint32_t runtime_policy_image_generation_timeout_default_ms(void); +uint32_t runtime_policy_image_generation_timeout_min_ms(void); +uint32_t runtime_policy_image_generation_timeout_max_ms(void); + +uint32_t runtime_policy_image_download_timeout_default_ms(void); +uint32_t runtime_policy_image_download_timeout_min_ms(void); +uint32_t runtime_policy_image_download_timeout_max_ms(void); + +// ---------- runtime_diagnostics ---------- +typedef enum { + RUNTIME_DIAG_COUNTER_LIFECYCLE_START_ATTEMPT = 0, + RUNTIME_DIAG_COUNTER_LIFECYCLE_START_SUCCESS, + RUNTIME_DIAG_COUNTER_LIFECYCLE_START_FAILED, + RUNTIME_DIAG_COUNTER_LIFECYCLE_START_RETRY, + RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_ATTEMPT, + RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_SUCCESS, + RUNTIME_DIAG_COUNTER_LIFECYCLE_STOP_FAILED, + RUNTIME_DIAG_COUNTER_WIFI_CONNECT_SUCCESS, + RUNTIME_DIAG_COUNTER_WIFI_CONNECT_FAILED, + RUNTIME_DIAG_COUNTER_WIFI_CONNECT_TIMEOUT, + RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUBMITTED, + RUNTIME_DIAG_COUNTER_PRINTER_JOB_SUCCESS, + RUNTIME_DIAG_COUNTER_PRINTER_JOB_FAILED, + RUNTIME_DIAG_COUNTER_PRINTER_JOB_CANCELED, + RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_ATTEMPT, + RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_SUCCESS, + RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_FAILED, + RUNTIME_DIAG_COUNTER_IMAGE_GENERATE_TIMEOUT, + RUNTIME_DIAG_COUNTER_REST_RESPONSES_TOTAL, + RUNTIME_DIAG_COUNTER_REST_ERRORS_TOTAL, + RUNTIME_DIAG_COUNTER_MAX, +} runtime_diag_counter_t; + +typedef enum { + RUNTIME_DIAG_GAUGE_LIFECYCLE_STATE = 0, + RUNTIME_DIAG_GAUGE_STATUS_POLL_PAUSE_DEPTH, + RUNTIME_DIAG_GAUGE_PRINTER_QUEUE_DEPTH, + RUNTIME_DIAG_GAUGE_MAX, +} runtime_diag_gauge_t; + +typedef struct { + uint64_t counters[RUNTIME_DIAG_COUNTER_MAX]; + int32_t gauges[RUNTIME_DIAG_GAUGE_MAX]; + int64_t last_error_ms; + esp_err_t last_error_code; + char last_error_source[32]; + char last_error_message[96]; +} runtime_diag_snapshot_t; + +void runtime_diag_counter_add(runtime_diag_counter_t counter, uint32_t delta); +void runtime_diag_set_gauge(runtime_diag_gauge_t gauge, int32_t value); +void runtime_diag_record_error(const char *source, esp_err_t code, const char *message); +void runtime_diag_get_snapshot(runtime_diag_snapshot_t *out_snapshot); + +const char *runtime_diag_counter_name(runtime_diag_counter_t counter); +const char *runtime_diag_gauge_name(runtime_diag_gauge_t gauge); + +#ifdef __cplusplus +} +#endif diff --git a/components/platform/internal/.gitkeep b/components/platform/internal/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/platform/internal/display_lcd_decode_image.h b/components/platform/internal/display_lcd_decode_image.h new file mode 100644 index 0000000..421ec6f --- /dev/null +++ b/components/platform/internal/display_lcd_decode_image.h @@ -0,0 +1,20 @@ +#pragma once + +#include +#include + +#include "esp_err.h" + +esp_err_t platform_lcd_decode_png_rgb565(const uint8_t *png, + size_t png_len, + uint16_t **out_pixels, + uint16_t *out_width, + uint16_t *out_height, + char *err, + size_t err_len); + +esp_err_t platform_lcd_decode_demo_png(uint16_t **out_pixels, + uint16_t *out_width, + uint16_t *out_height, + char *err, + size_t err_len); diff --git a/components/platform/internal/display_lcd_module.h b/components/platform/internal/display_lcd_module.h new file mode 100644 index 0000000..e1a265f --- /dev/null +++ b/components/platform/internal/display_lcd_module.h @@ -0,0 +1,31 @@ +#pragma once + +#include +#include + +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +esp_err_t lcd_module_init(void); +esp_err_t lcd_module_start_demo(void); +esp_err_t lcd_module_show_raster_1bpp(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len); +esp_err_t lcd_module_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len); +void lcd_module_mark_shared_spi_dirty(void); +void lcd_module_deinit(void); + +#ifdef __cplusplus +} +#endif diff --git a/components/platform/internal/display_st7789p3.h b/components/platform/internal/display_st7789p3.h new file mode 100644 index 0000000..def681b --- /dev/null +++ b/components/platform/internal/display_st7789p3.h @@ -0,0 +1,97 @@ +#pragma once + +#include +#include +#include + +#include "driver/spi_master.h" +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct st7789p3_panel_t *st7789p3_handle_t; + +#define ST7789P3_MADCTL_MY 0x80 +#define ST7789P3_MADCTL_MX 0x40 +#define ST7789P3_MADCTL_MV 0x20 +#define ST7789P3_MADCTL_ML 0x10 +#define ST7789P3_MADCTL_BGR 0x08 +#define ST7789P3_MADCTL_MH 0x04 + +typedef struct { + spi_host_device_t spi_host; + int pin_mosi; + int pin_miso; + int pin_sclk; + int pin_cs; + int pin_dc; + int pin_rst; + int pin_bckl; + uint32_t pclk_hz; + uint8_t spi_mode; + int queue_size; + size_t max_transfer_sz; + uint16_t h_res; + uint16_t v_res; + uint16_t x_gap; + uint16_t y_gap; + uint8_t madctl_val; + bool invert_color; + bool swap_color_bytes; + int backlight_on_level; + bool init_spi_bus; +} st7789p3_config_t; + +#define ST7789P3_CONFIG_DEFAULT() \ + { \ + .spi_host = SPI2_HOST, \ + .pin_mosi = -1, \ + .pin_miso = -1, \ + .pin_sclk = -1, \ + .pin_cs = -1, \ + .pin_dc = -1, \ + .pin_rst = -1, \ + .pin_bckl = -1, \ + .pclk_hz = 10 * 1000 * 1000, \ + .spi_mode = 0, \ + .queue_size = 7, \ + .max_transfer_sz = 0, \ + .h_res = 320, \ + .v_res = 240, \ + .x_gap = 0, \ + .y_gap = 0, \ + .madctl_val = ST7789P3_MADCTL_MX | ST7789P3_MADCTL_MV, \ + .invert_color = false, \ + .swap_color_bytes = false, \ + .backlight_on_level = 1, \ + .init_spi_bus = true, \ + } + +esp_err_t st7789p3_new_panel(const st7789p3_config_t *config, st7789p3_handle_t *ret_panel); +esp_err_t st7789p3_del(st7789p3_handle_t panel); + +esp_err_t st7789p3_reset(st7789p3_handle_t panel); +esp_err_t st7789p3_init(st7789p3_handle_t panel); + +esp_err_t st7789p3_set_backlight(st7789p3_handle_t panel, bool on); +esp_err_t st7789p3_set_madctl(st7789p3_handle_t panel, uint8_t madctl_val); +esp_err_t st7789p3_set_invert(st7789p3_handle_t panel, bool invert_color); +esp_err_t st7789p3_set_swap_color_bytes(st7789p3_handle_t panel, bool swap_color_bytes); +esp_err_t st7789p3_recover_spi_bus(st7789p3_handle_t panel); + +esp_err_t st7789p3_set_window( + st7789p3_handle_t panel, uint16_t x_start, uint16_t y_start, uint16_t x_end, uint16_t y_end); +esp_err_t st7789p3_draw_bitmap(st7789p3_handle_t panel, + uint16_t x_start, + uint16_t y_start, + uint16_t x_end, + uint16_t y_end, + const uint16_t *color_data); + +esp_err_t st7789p3_fill_color(st7789p3_handle_t panel, uint16_t color); + +#ifdef __cplusplus +} +#endif diff --git a/components/platform/src/.gitkeep b/components/platform/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/components/platform/src/ble_printer_client.c b/components/platform/src/ble_printer_client.c new file mode 100644 index 0000000..eb3af89 --- /dev/null +++ b/components/platform/src/ble_printer_client.c @@ -0,0 +1,706 @@ +#include "platform.h" + +#include +#include + +#include "esp_err.h" +#include "esp_log.h" +#include "esp_nimble_hci.h" +#include "freertos/FreeRTOS.h" +#include "freertos/event_groups.h" +#include "freertos/semphr.h" +#include "host/ble_gatt.h" +#include "host/ble_hs.h" +#include "nimble/nimble_port.h" +#include "nimble/nimble_port_freertos.h" +#include "os/os_mbuf.h" +#include "services/gap/ble_svc_gap.h" +#include "services/gatt/ble_svc_gatt.h" + +#define PRINTER_SERVICE_UUID16 0xFFF0 +#define PRINTER_NOTIFY_UUID16 0xFFF1 +#define PRINTER_WRITE_UUID16 0xFFF2 +#define CCCD_UUID16 0x2902 +#define PRINTER_NAME_PRIMARY "TQPrinter" +#define PRINTER_NAME_LEGACY "lyfPrinter" + +#define EVT_CONNECTED BIT0 +#define EVT_READY BIT1 +#define EVT_FAILED BIT2 + +static const char *TAG = "ble_client"; + +static EventGroupHandle_t s_evt_group; +static SemaphoreHandle_t s_lock; + +static ble_frame_rx_cb_t s_rx_cb; + +static uint8_t s_addr_type; +static ble_addr_t s_target_addr; +static char s_target_name[32] = PRINTER_NAME_PRIMARY; +static bool s_match_any_compatible; + +static uint16_t s_conn_handle = BLE_HS_CONN_HANDLE_NONE; +static uint16_t s_service_start; +static uint16_t s_service_end; +static uint16_t s_notify_val_handle; +static uint16_t s_write_val_handle; +static uint16_t s_cccd_handle; +static uint16_t s_mtu = 23; + +static bool s_scanning; +static bool s_notify_ready; +static bool s_host_synced; +static bool s_initialized; +static bool s_connecting; +static uint32_t s_connect_timeout_ms = 15000; + +static uint16_t uuid16(const ble_uuid_t *uuid) { + if (uuid == NULL || uuid->type != BLE_UUID_TYPE_16) { + return 0; + } + return BLE_UUID16(uuid)->value; +} + +static bool adv_has_uuid16(const struct ble_hs_adv_fields *fields, uint16_t target_uuid) { + if (fields == NULL || fields->uuids16 == NULL || fields->num_uuids16 == 0) { + return false; + } + for (uint8_t i = 0; i < fields->num_uuids16; ++i) { + if (fields->uuids16[i].value == target_uuid) { + return true; + } + } + return false; +} + +static size_t normalize_name(const char *in, char *out, size_t out_cap) { + if (in == NULL || out == NULL || out_cap == 0) { + return 0; + } + + const char *start = in; + while (*start != '\0' && isspace((unsigned char)*start)) { + ++start; + } + if (*start == '"' || *start == '\'') { + ++start; + } + + size_t len = strlen(start); + while (len > 0 && isspace((unsigned char)start[len - 1])) { + --len; + } + if (len > 0 && (start[len - 1] == '"' || start[len - 1] == '\'')) { + --len; + } + + size_t out_len = 0; + for (size_t i = 0; i < len && out_len + 1 < out_cap; ++i) { + unsigned char c = (unsigned char)start[i]; + if (isupper(c)) { + c = (unsigned char)tolower(c); + } + out[out_len++] = (char)c; + } + out[out_len] = '\0'; + return out_len; +} + +static bool normalized_name_match(const char *adv_name, const char *target_name) { + char adv[40] = {0}; + char target[40] = {0}; + size_t adv_len = normalize_name(adv_name, adv, sizeof(adv)); + size_t target_len = normalize_name(target_name, target, sizeof(target)); + if (adv_len == 0 || target_len == 0) { + return false; + } + if (strcmp(adv, target) == 0) { + return true; + } + // Be tolerant of shortened or prefixed names. + return (strstr(adv, target) != NULL) || (strstr(target, adv) != NULL); +} + +static bool is_known_printer_name(const char *name) { + return normalized_name_match(name, PRINTER_NAME_PRIMARY) || + normalized_name_match(name, PRINTER_NAME_LEGACY); +} + +static bool target_name_match_with_alias(const char *adv_name, const char *target_name) { + if (normalized_name_match(adv_name, target_name)) { + return true; + } + if (!is_known_printer_name(target_name)) { + return false; + } + return is_known_printer_name(adv_name); +} + +static void reset_discovery_state(void) { + s_service_start = 0; + s_service_end = 0; + s_notify_val_handle = 0; + s_write_val_handle = 0; + s_cccd_handle = 0; + s_notify_ready = false; + s_mtu = 23; +} + +static void signal_failure(void) { + xEventGroupSetBits(s_evt_group, EVT_FAILED); +} + +static void signal_ready(void) { + xEventGroupSetBits(s_evt_group, EVT_READY); +} + +static int dsc_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + uint16_t chr_val_handle, + const struct ble_gatt_dsc *dsc, + void *arg); + +static int chr_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_chr *chr, + void *arg); + +static int svc_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_svc *service, + void *arg); + +static int cccd_write_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + struct ble_gatt_attr *attr, + void *arg) { + (void)conn_handle; + (void)attr; + (void)arg; + + if (error->status != 0) { + ESP_LOGE(TAG, "CCCD write failed status=%d", error->status); + signal_failure(); + return 0; + } + + s_notify_ready = true; + ESP_LOGI(TAG, "Notify subscription enabled"); + signal_ready(); + return 0; +} + +static int dsc_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + uint16_t chr_val_handle, + const struct ble_gatt_dsc *dsc, + void *arg) { + (void)chr_val_handle; + (void)arg; + + if (error->status == 0 && dsc != NULL) { + if (uuid16(&dsc->uuid.u) == CCCD_UUID16) { + s_cccd_handle = dsc->handle; + ESP_LOGI(TAG, "Found CCCD handle=%u", s_cccd_handle); + } + return 0; + } + + if (error->status == BLE_HS_EDONE) { + if (s_cccd_handle == 0) { + ESP_LOGW(TAG, "CCCD not found, fallback to val_handle+1"); + s_cccd_handle = s_notify_val_handle + 1; + } + + uint8_t cccd[2] = {0x01, 0x00}; + int rc = ble_gattc_write_flat(conn_handle, s_cccd_handle, cccd, sizeof(cccd), cccd_write_cb, NULL); + if (rc != 0) { + ESP_LOGE(TAG, "ble_gattc_write_flat CCCD failed rc=%d", rc); + signal_failure(); + } + return 0; + } + + ESP_LOGE(TAG, "Descriptor discovery failed status=%d", error->status); + signal_failure(); + return 0; +} + +static int chr_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_chr *chr, + void *arg) { + (void)arg; + + if (error->status == 0 && chr != NULL) { + uint16_t id = uuid16(&chr->uuid.u); + if (id == PRINTER_NOTIFY_UUID16) { + s_notify_val_handle = chr->val_handle; + ESP_LOGI(TAG, "Found notify char handle=%u", s_notify_val_handle); + } else if (id == PRINTER_WRITE_UUID16) { + s_write_val_handle = chr->val_handle; + ESP_LOGI(TAG, "Found write char handle=%u", s_write_val_handle); + } + return 0; + } + + if (error->status == BLE_HS_EDONE) { + if (s_notify_val_handle == 0 || s_write_val_handle == 0) { + ESP_LOGE(TAG, + "Characteristic discovery incomplete notify=%u write=%u", + s_notify_val_handle, + s_write_val_handle); + signal_failure(); + return 0; + } + + uint16_t end_handle = (s_write_val_handle > s_notify_val_handle) + ? (uint16_t)(s_write_val_handle - 1) + : s_service_end; + + if (end_handle <= s_notify_val_handle) { + end_handle = s_service_end; + } + + int rc = ble_gattc_disc_all_dscs(conn_handle, + s_notify_val_handle, + end_handle, + dsc_disc_cb, + NULL); + if (rc != 0) { + ESP_LOGE(TAG, "Descriptor discovery start failed rc=%d", rc); + signal_failure(); + } + return 0; + } + + ESP_LOGE(TAG, "Characteristic discovery failed status=%d", error->status); + signal_failure(); + return 0; +} + +static int svc_disc_cb(uint16_t conn_handle, + const struct ble_gatt_error *error, + const struct ble_gatt_svc *service, + void *arg) { + (void)arg; + + if (error->status == 0 && service != NULL) { + if (uuid16(&service->uuid.u) == PRINTER_SERVICE_UUID16) { + s_service_start = service->start_handle; + s_service_end = service->end_handle; + ESP_LOGI(TAG, "Found printer service [%u, %u]", s_service_start, s_service_end); + } + return 0; + } + + if (error->status == BLE_HS_EDONE) { + uint16_t start = s_service_start; + uint16_t end = s_service_end; + if (start == 0 || end == 0) { + // Android app searches all services/chars for FFF1/FFF2. + // Use a global fallback range for broader compatibility. + start = 1; + end = 0xFFFF; + ESP_LOGW(TAG, "Printer service 0x%04x not found; fallback char discovery in full handle range", PRINTER_SERVICE_UUID16); + } + + int rc = ble_gattc_disc_all_chrs(conn_handle, + start, + end, + chr_disc_cb, + NULL); + if (rc != 0) { + ESP_LOGE(TAG, "Start characteristic discovery failed rc=%d", rc); + signal_failure(); + } + return 0; + } + + ESP_LOGE(TAG, "Service discovery failed status=%d", error->status); + signal_failure(); + return 0; +} + +static void start_service_discovery(void) { + int rc = ble_gattc_disc_all_svcs(s_conn_handle, svc_disc_cb, NULL); + if (rc != 0) { + ESP_LOGE(TAG, "ble_gattc_disc_all_svcs failed rc=%d", rc); + signal_failure(); + } +} + +static void start_scan(void); + +static void stop_scan_if_running(void) { + if (s_scanning) { + ble_gap_disc_cancel(); + s_scanning = false; + } +} + +static int gap_event_cb(struct ble_gap_event *event, void *arg) { + (void)arg; + + switch (event->type) { + case BLE_GAP_EVENT_DISC: { + if (!s_scanning) { + return 0; + } + struct ble_hs_adv_fields fields; + memset(&fields, 0, sizeof(fields)); + + int rc = ble_hs_adv_parse_fields(&fields, + event->disc.data, + event->disc.length_data); + if (rc != 0) { + return 0; + } + + char name[32] = {0}; + bool has_name = (fields.name_len > 0 && fields.name != NULL); + if (has_name) { + size_t n = fields.name_len < sizeof(name) - 1 ? fields.name_len : sizeof(name) - 1; + memcpy(name, fields.name, n); + } + + if (s_match_any_compatible) { + bool uuid_match = adv_has_uuid16(&fields, PRINTER_SERVICE_UUID16); + bool name_match = has_name && is_known_printer_name(name); + if (!uuid_match && !name_match) { + return 0; + } + ESP_LOGI(TAG, + "Found compatible device '%s' RSSI=%d (uuid_match=%d)", + has_name ? name : "", + event->disc.rssi, + uuid_match ? 1 : 0); + } else { + if (!has_name || !target_name_match_with_alias(name, s_target_name)) { + return 0; + } + ESP_LOGI(TAG, "Found target device '%s' RSSI=%d", name, event->disc.rssi); + } + + s_target_addr = event->disc.addr; + stop_scan_if_running(); + + struct ble_gap_conn_params conn_params; + memset(&conn_params, 0, sizeof(conn_params)); + conn_params.scan_itvl = 0x0010; + conn_params.scan_window = 0x0010; + conn_params.itvl_min = 0x0018; + conn_params.itvl_max = 0x0028; + conn_params.latency = 0; + conn_params.supervision_timeout = 0x0100; + conn_params.min_ce_len = 0x0010; + conn_params.max_ce_len = 0x0300; + + rc = ble_gap_connect(s_addr_type, + &s_target_addr, + s_connect_timeout_ms > 30000 ? 30000 : s_connect_timeout_ms, + &conn_params, + gap_event_cb, + NULL); + if (rc != 0) { + ESP_LOGE(TAG, "ble_gap_connect failed rc=%d", rc); + s_connecting = false; + signal_failure(); + } else { + ESP_LOGI(TAG, "Connecting..."); + } + + return 0; + } + + case BLE_GAP_EVENT_DISC_COMPLETE: + s_scanning = false; + return 0; + + case BLE_GAP_EVENT_CONNECT: + if (event->connect.status == 0) { + if (!s_connecting) { + (void)ble_gap_terminate(event->connect.conn_handle, BLE_ERR_REM_USER_CONN_TERM); + return 0; + } + s_connecting = false; + s_conn_handle = event->connect.conn_handle; + xEventGroupSetBits(s_evt_group, EVT_CONNECTED); + ESP_LOGI(TAG, "Connected handle=%u", s_conn_handle); + + ble_gattc_exchange_mtu(s_conn_handle, NULL, NULL); + start_service_discovery(); + } else { + s_connecting = false; + ESP_LOGE(TAG, "Connect failed status=%d", event->connect.status); + signal_failure(); + } + return 0; + + case BLE_GAP_EVENT_DISCONNECT: + ESP_LOGW(TAG, "Disconnected reason=%d", event->disconnect.reason); + s_connecting = false; + s_conn_handle = BLE_HS_CONN_HANDLE_NONE; + s_notify_ready = false; + reset_discovery_state(); + return 0; + + case BLE_GAP_EVENT_MTU: + s_mtu = event->mtu.value; + ESP_LOGI(TAG, "MTU updated to %u", s_mtu); + return 0; + + case BLE_GAP_EVENT_NOTIFY_RX: { + if (event->notify_rx.om == NULL || s_rx_cb == NULL) { + return 0; + } + + uint16_t data_len = OS_MBUF_PKTLEN(event->notify_rx.om); + if (data_len == 0) { + return 0; + } + + uint8_t buf[256]; + uint16_t out_len = 0; + if (data_len > sizeof(buf)) { + ESP_LOGW(TAG, "Notify packet too large len=%u", data_len); + return 0; + } + + int rc = ble_hs_mbuf_to_flat(event->notify_rx.om, buf, sizeof(buf), &out_len); + if (rc != 0) { + ESP_LOGW(TAG, "ble_hs_mbuf_to_flat notify failed rc=%d", rc); + return 0; + } + + s_rx_cb(buf, out_len); + return 0; + } + + default: + return 0; + } +} + +static void start_scan(void) { + struct ble_gap_disc_params params; + memset(¶ms, 0, sizeof(params)); + // Keep duplicates so we can receive scan response updates carrying full local name. + params.filter_duplicates = 0; + params.passive = 0; + params.itvl = 0x0010; + params.window = 0x0010; + + stop_scan_if_running(); + + int rc = ble_gap_disc(s_addr_type, BLE_HS_FOREVER, ¶ms, gap_event_cb, NULL); + if (rc != 0) { + ESP_LOGE(TAG, "ble_gap_disc failed rc=%d", rc); + signal_failure(); + return; + } + + s_scanning = true; + if (s_match_any_compatible) { + ESP_LOGI(TAG, "Scanning for compatible printer (service 0x%04x)", PRINTER_SERVICE_UUID16); + } else { + ESP_LOGI(TAG, "Scanning for %s", s_target_name); + } +} + +static void ble_on_reset(int reason) { + ESP_LOGE(TAG, "BLE reset reason=%d", reason); +} + +static void ble_on_sync(void) { + int rc = ble_hs_id_infer_auto(0, &s_addr_type); + if (rc != 0) { + ESP_LOGE(TAG, "ble_hs_id_infer_auto failed rc=%d", rc); + } + s_host_synced = true; +} + +static void nimble_host_task(void *param) { + (void)param; + nimble_port_run(); + nimble_port_freertos_deinit(); +} + +esp_err_t ble_printer_client_init(ble_frame_rx_cb_t rx_cb) { + s_rx_cb = rx_cb; + + if (s_initialized) { + reset_discovery_state(); + return ESP_OK; + } + + // NimBLE emits very chatty INFO logs during each chunk write. + // Lowering these logs reduces serial I/O overhead and improves runtime smoothness. + esp_log_level_set("NimBLE", ESP_LOG_WARN); + esp_log_level_set("BLE_INIT", ESP_LOG_WARN); + + s_evt_group = xEventGroupCreate(); + if (s_evt_group == NULL) { + return ESP_ERR_NO_MEM; + } + + s_lock = xSemaphoreCreateMutex(); + if (s_lock == NULL) { + vEventGroupDelete(s_evt_group); + s_evt_group = NULL; + return ESP_ERR_NO_MEM; + } + + esp_err_t err = nimble_port_init(); + if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) { + return err; + } + ble_hs_cfg.reset_cb = ble_on_reset; + ble_hs_cfg.sync_cb = ble_on_sync; + + ble_svc_gap_init(); + ble_svc_gatt_init(); + + nimble_port_freertos_init(nimble_host_task); + + reset_discovery_state(); + s_initialized = true; + return ESP_OK; +} + +esp_err_t ble_printer_client_connect(const char *target_name, uint32_t timeout_ms) { + if (!s_initialized || s_lock == NULL || s_evt_group == NULL) { + return ESP_ERR_INVALID_STATE; + } + + uint32_t effective_timeout_ms = timeout_ms; + if (effective_timeout_ms < 1000) { + effective_timeout_ms = 1000; + } else if (effective_timeout_ms > 60000) { + effective_timeout_ms = 60000; + } + + s_match_any_compatible = false; + if (target_name != NULL && target_name[0] != '\0') { + if (strcmp(target_name, "*") == 0) { + s_match_any_compatible = true; + } else { + strlcpy(s_target_name, target_name, sizeof(s_target_name)); + } + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(3000)) != pdTRUE) { + return ESP_ERR_TIMEOUT; + } + + if (s_conn_handle != BLE_HS_CONN_HANDLE_NONE && s_notify_ready) { + xSemaphoreGive(s_lock); + return ESP_OK; + } + if (s_connecting) { + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + xEventGroupClearBits(s_evt_group, EVT_CONNECTED | EVT_READY | EVT_FAILED); + reset_discovery_state(); + s_connect_timeout_ms = effective_timeout_ms; + s_connecting = true; + + int wait_sync_ms = 3000; + while (!s_host_synced && wait_sync_ms > 0) { + vTaskDelay(pdMS_TO_TICKS(20)); + wait_sync_ms -= 20; + } + if (!s_host_synced) { + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + start_scan(); + xSemaphoreGive(s_lock); + + EventBits_t bits = xEventGroupWaitBits(s_evt_group, + EVT_READY | EVT_FAILED, + pdFALSE, + pdFALSE, + pdMS_TO_TICKS(effective_timeout_ms)); + + if (bits & EVT_READY) { + return ESP_OK; + } + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(1000)) == pdTRUE) { + stop_scan_if_running(); + if (s_conn_handle != BLE_HS_CONN_HANDLE_NONE) { + (void)ble_gap_terminate(s_conn_handle, BLE_ERR_REM_USER_CONN_TERM); + } + s_connecting = false; + reset_discovery_state(); + xSemaphoreGive(s_lock); + } + + if (bits & EVT_FAILED) { + return ESP_FAIL; + } + return ESP_ERR_TIMEOUT; +} + +void ble_printer_client_disconnect(void) { + if (!s_initialized || s_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(2000)) != pdTRUE) { + return; + } + + stop_scan_if_running(); + + if (s_conn_handle != BLE_HS_CONN_HANDLE_NONE) { + ble_gap_terminate(s_conn_handle, BLE_ERR_REM_USER_CONN_TERM); + } + + s_connecting = false; + s_conn_handle = BLE_HS_CONN_HANDLE_NONE; + reset_discovery_state(); + xSemaphoreGive(s_lock); +} + +bool ble_printer_client_is_connected(void) { + if (!s_initialized) { + return false; + } + return (s_conn_handle != BLE_HS_CONN_HANDLE_NONE) && s_notify_ready; +} + +void ble_printer_client_get_link_state(ble_link_state_t *out_state) { + if (out_state == NULL) { + return; + } + + out_state->connected = (s_conn_handle != BLE_HS_CONN_HANDLE_NONE); + out_state->notify_ready = s_notify_ready; + out_state->mtu = s_mtu; +} + +esp_err_t ble_printer_client_write(const uint8_t *data, size_t len) { + if (data == NULL || len == 0) { + return ESP_ERR_INVALID_ARG; + } + + if (!ble_printer_client_is_connected() || s_write_val_handle == 0) { + return ESP_ERR_INVALID_STATE; + } + + int rc = ble_gattc_write_no_rsp_flat(s_conn_handle, + s_write_val_handle, + data, + len); + if (rc != 0) { + ESP_LOGW(TAG, "write_no_rsp failed rc=%d", rc); + return ESP_FAIL; + } + + return ESP_OK; +} diff --git a/components/platform/src/direct_thermal_printer.c b/components/platform/src/direct_thermal_printer.c new file mode 100644 index 0000000..c79f170 --- /dev/null +++ b/components/platform/src/direct_thermal_printer.c @@ -0,0 +1,1020 @@ +#include "platform.h" + +#include +#include +#include + +#include "driver/gpio.h" +#include "esp_adc/adc_oneshot.h" +#include "esp_log.h" +#include "esp_rom_sys.h" +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" +#include "freertos/task.h" +#include "sdkconfig.h" + +#ifndef CONFIG_TQ_DIRECT_PRINTER_ENABLE +#define CONFIG_TQ_DIRECT_PRINTER_ENABLE 1 +#endif + +#ifndef CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH +#define CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH 1 +#endif + +#if CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH +#define BOOST_DEFAULT_ACTIVE_HIGH 1 +#else +#define BOOST_DEFAULT_ACTIVE_HIGH 0 +#endif + +#define ADC_RAW_MAX 4095 +#define DEBUG_SHIFT_CLOCK_US_MIN 1 +#define DEBUG_SHIFT_CLOCK_US_MAX 50 +#define DEBUG_LATCH_PULSE_US_MIN 1 +#define DEBUG_LATCH_PULSE_US_MAX 50 + +static const uint16_t k_default_shift_clock_high_us = 5; +static const uint16_t k_default_shift_clock_low_us = 5; +static const uint16_t k_default_latch_pulse_us = 1; +static const bool k_default_strobe_active_high = true; + +static const char *TAG = "direct_printer"; +static const uint8_t k_print_yield_lines = 8; +static const uint16_t k_gap_yield_steps = 32; + +typedef struct { + bool ready; + adc_unit_t unit; + adc_channel_t channel; +} adc_pin_t; + +typedef struct { + uint16_t shift_clock_high_us; + uint16_t shift_clock_low_us; + uint16_t latch_pulse_us; + bool strobe_active_high; + bool boost_active_high; + uint16_t override_strobe_on_us; + uint16_t override_strobe_interval_us; + uint16_t override_motor_step_us; + uint8_t override_steps_per_line; +} direct_debug_config_t; + +typedef struct { + bool initialized; + bool connected; + uint8_t motor_phase; + direct_debug_config_t debug; + SemaphoreHandle_t lock; + adc_oneshot_unit_handle_t adc1_handle; + adc_oneshot_unit_handle_t adc2_handle; + adc_pin_t battery_adc; + adc_pin_t ntc_adc; +} direct_printer_state_t; + +static direct_printer_state_t s_state; + +static const uint8_t k_motor_step_table[4] = {0x05, 0x09, 0x0A, 0x06}; + +static int boost_on_level_locked(void) { + return s_state.debug.boost_active_high ? 1 : 0; +} + +static int boost_off_level_locked(void) { + return s_state.debug.boost_active_high ? 0 : 1; +} + +static int strobe_active_level_locked(void) { + return s_state.debug.strobe_active_high ? 1 : 0; +} + +static int strobe_idle_level_locked(void) { + return s_state.debug.strobe_active_high ? 0 : 1; +} + +static void set_debug_defaults_locked(void) { + memset(&s_state.debug, 0, sizeof(s_state.debug)); + s_state.debug.shift_clock_high_us = k_default_shift_clock_high_us; + s_state.debug.shift_clock_low_us = k_default_shift_clock_low_us; + s_state.debug.latch_pulse_us = k_default_latch_pulse_us; + s_state.debug.strobe_active_high = k_default_strobe_active_high; + s_state.debug.boost_active_high = BOOST_DEFAULT_ACTIVE_HIGH != 0; +} + +static bool is_gpio_valid(int gpio_num) { + return gpio_num >= 0; +} + +static void write_err(char *err, size_t err_len, const char *text) { + if (err != NULL && err_len > 0) { + strlcpy(err, text, err_len); + } +} + +static void set_gpio_level_if_valid(int gpio_num, int level) { + if (!is_gpio_valid(gpio_num)) { + return; + } + (void)gpio_set_level(gpio_num, level); +} + +static esp_err_t config_output_pin(int gpio_num, int level, const char *name) { + if (!is_gpio_valid(gpio_num)) { + return ESP_OK; + } + + gpio_config_t cfg = { + .pin_bit_mask = 1ULL << gpio_num, + .mode = GPIO_MODE_OUTPUT, + .pull_up_en = GPIO_PULLUP_DISABLE, + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .intr_type = GPIO_INTR_DISABLE, + }; + esp_err_t err = gpio_config(&cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_config output failed: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + return err; + } + err = gpio_set_level(gpio_num, level); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_set_level failed: %s pin=%d level=%d err=%s", name, gpio_num, level, esp_err_to_name(err)); + } + return err; +} + +static esp_err_t config_input_pin(int gpio_num, bool pull_up, const char *name) { + if (!is_gpio_valid(gpio_num)) { + return ESP_OK; + } + + gpio_config_t cfg = { + .pin_bit_mask = 1ULL << gpio_num, + .mode = GPIO_MODE_INPUT, + .pull_up_en = pull_up ? GPIO_PULLUP_ENABLE : GPIO_PULLUP_DISABLE, + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .intr_type = GPIO_INTR_DISABLE, + }; + esp_err_t err = gpio_config(&cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_config input failed: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + } + return err; +} + +static esp_err_t ensure_shared_shift_pins_gpio_locked(void) { + platform_display_mark_shared_spi_dirty(); + + esp_err_t err = config_output_pin(CONFIG_TQ_SPI_SHARED_MOSI_PIN, 0, "print_mosi"); + if (err != ESP_OK) { + return err; + } + return config_output_pin(CONFIG_TQ_SPI_SHARED_CLK_PIN, 0, "print_clk"); +} + +static void set_stb_level_locked(int level) { + int out_level = level ? strobe_active_level_locked() : strobe_idle_level_locked(); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_STB_12_PIN, out_level); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_STB_34_PIN, out_level); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_STB_56_PIN, out_level); +} + +static void motor_apply_pattern_locked(uint8_t pattern) { + set_gpio_level_if_valid(CONFIG_TQ_PRINT_OUTA_P_PIN, (pattern >> 0) & 0x01); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_OUTA_N_PIN, (pattern >> 1) & 0x01); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_OUTB_P_PIN, (pattern >> 2) & 0x01); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_OUTB_N_PIN, (pattern >> 3) & 0x01); +} + +static void motor_off_locked(void) { + motor_apply_pattern_locked(0x00); +} + +static void safe_drive_off_locked(bool keep_boost_on) { + set_stb_level_locked(0); + set_gpio_level_if_valid(CONFIG_TQ_SPI_SHARED_MOSI_PIN, 0); + set_gpio_level_if_valid(CONFIG_TQ_SPI_SHARED_CLK_PIN, 0); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_LAT_PIN, 1); + motor_off_locked(); + if (!keep_boost_on) { + set_gpio_level_if_valid(CONFIG_TQ_KEY_PRINT_PIN, boost_off_level_locked()); + } +} + +static void pulse_latch_locked(void) { + uint16_t latch_us = s_state.debug.latch_pulse_us; + if (latch_us < DEBUG_LATCH_PULSE_US_MIN) { + latch_us = DEBUG_LATCH_PULSE_US_MIN; + } else if (latch_us > DEBUG_LATCH_PULSE_US_MAX) { + latch_us = DEBUG_LATCH_PULSE_US_MAX; + } + set_gpio_level_if_valid(CONFIG_TQ_PRINT_LAT_PIN, 0); + esp_rom_delay_us(latch_us); + set_gpio_level_if_valid(CONFIG_TQ_PRINT_LAT_PIN, 1); +} + +static void fire_strobe_locked(uint16_t on_us, uint16_t interval_us) { + set_stb_level_locked(1); + esp_rom_delay_us(on_us); + set_stb_level_locked(0); + if (interval_us > 0) { + esp_rom_delay_us(interval_us); + } +} + +static void motor_step_once_locked(uint16_t step_delay_us) { + uint8_t pattern = k_motor_step_table[s_state.motor_phase & 0x03]; + motor_apply_pattern_locked(pattern); + if (step_delay_us > 0) { + esp_rom_delay_us(step_delay_us); + } + if (runtime_policy_direct_printer_motor_reverse()) { + s_state.motor_phase = (uint8_t)((s_state.motor_phase + 3) & 0x03); + } else { + s_state.motor_phase = (uint8_t)((s_state.motor_phase + 1) & 0x03); + } +} + +static void write_line_bits_locked(const uint8_t *line, size_t line_bytes) { + uint16_t high_us = s_state.debug.shift_clock_high_us; + uint16_t low_us = s_state.debug.shift_clock_low_us; + if (high_us < DEBUG_SHIFT_CLOCK_US_MIN) { + high_us = DEBUG_SHIFT_CLOCK_US_MIN; + } else if (high_us > DEBUG_SHIFT_CLOCK_US_MAX) { + high_us = DEBUG_SHIFT_CLOCK_US_MAX; + } + if (low_us < DEBUG_SHIFT_CLOCK_US_MIN) { + low_us = DEBUG_SHIFT_CLOCK_US_MIN; + } else if (low_us > DEBUG_SHIFT_CLOCK_US_MAX) { + low_us = DEBUG_SHIFT_CLOCK_US_MAX; + } + + for (size_t i = 0; i < line_bytes; ++i) { + uint8_t byte = line[i]; + for (int bit = 7; bit >= 0; --bit) { + int pixel = ((byte >> bit) & 0x01) ? 1 : 0; + set_gpio_level_if_valid(CONFIG_TQ_SPI_SHARED_MOSI_PIN, pixel); + set_gpio_level_if_valid(CONFIG_TQ_SPI_SHARED_CLK_PIN, 1); + esp_rom_delay_us(high_us); + set_gpio_level_if_valid(CONFIG_TQ_SPI_SHARED_CLK_PIN, 0); + esp_rom_delay_us(low_us); + } + } +} + +static esp_err_t ensure_adc_unit(adc_unit_t unit, adc_oneshot_unit_handle_t *out_handle) { + if (out_handle == NULL) { + return ESP_ERR_INVALID_ARG; + } + + adc_oneshot_unit_handle_t *slot = NULL; + if (unit == ADC_UNIT_1) { + slot = &s_state.adc1_handle; + } else if (unit == ADC_UNIT_2) { + slot = &s_state.adc2_handle; + } else { + return ESP_ERR_NOT_SUPPORTED; + } + + if (*slot == NULL) { + adc_oneshot_unit_init_cfg_t cfg = { + .unit_id = unit, + .clk_src = ADC_RTC_CLK_SRC_DEFAULT, + .ulp_mode = ADC_ULP_MODE_DISABLE, + }; + esp_err_t err = adc_oneshot_new_unit(&cfg, slot); + if (err != ESP_OK) { + ESP_LOGW(TAG, "adc unit init failed: unit=%d err=%s", (int)unit, esp_err_to_name(err)); + return err; + } + } + + *out_handle = *slot; + return ESP_OK; +} + +static void init_adc_pin_if_possible(int gpio_num, const char *name, adc_pin_t *out_pin) { + if (out_pin == NULL) { + return; + } + + memset(out_pin, 0, sizeof(*out_pin)); + if (!is_gpio_valid(gpio_num)) { + return; + } + + adc_unit_t unit = ADC_UNIT_1; + adc_channel_t channel = ADC_CHANNEL_0; + esp_err_t err = adc_oneshot_io_to_channel(gpio_num, &unit, &channel); + if (err != ESP_OK) { + ESP_LOGW(TAG, "adc gpio unsupported: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + return; + } + + adc_oneshot_unit_handle_t handle = NULL; + err = ensure_adc_unit(unit, &handle); + if (err != ESP_OK) { + return; + } + + adc_oneshot_chan_cfg_t chan_cfg = { + .atten = ADC_ATTEN_DB_12, + .bitwidth = ADC_BITWIDTH_DEFAULT, + }; + err = adc_oneshot_config_channel(handle, channel, &chan_cfg); + if (err != ESP_OK) { + ESP_LOGW(TAG, "adc channel config failed: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + return; + } + + out_pin->ready = true; + out_pin->unit = unit; + out_pin->channel = channel; +} + +static esp_err_t read_adc_raw_locked(const adc_pin_t *pin, int *out_raw) { + if (pin == NULL || out_raw == NULL || !pin->ready) { + return ESP_ERR_INVALID_STATE; + } + + adc_oneshot_unit_handle_t handle = NULL; + if (pin->unit == ADC_UNIT_1) { + handle = s_state.adc1_handle; + } else if (pin->unit == ADC_UNIT_2) { + handle = s_state.adc2_handle; + } + + if (handle == NULL) { + return ESP_ERR_INVALID_STATE; + } + + return adc_oneshot_read(handle, pin->channel, out_raw); +} + +static bool read_paper_present_locked(int *out_level) { + if (!is_gpio_valid(CONFIG_TQ_PRINT_PAPER_PIN)) { + if (out_level != NULL) { + *out_level = -1; + } + return true; + } + int level = gpio_get_level(CONFIG_TQ_PRINT_PAPER_PIN); + if (out_level != NULL) { + *out_level = level; + } + return level == (int)runtime_policy_direct_printer_paper_present_level(); +} + +static uint16_t battery_raw_to_mv(int raw) { + if (raw < 0) { + raw = 0; + } + if (raw > ADC_RAW_MAX) { + raw = ADC_RAW_MAX; + } + float adc_mv = ((float)raw * 3300.0f) / (float)ADC_RAW_MAX; + float ratio = (float)runtime_policy_direct_printer_battery_divider_ratio_x1000() / 1000.0f; + float batt_mv = adc_mv * ratio; + if (batt_mv < 0.0f) { + batt_mv = 0.0f; + } + if (batt_mv > 65535.0f) { + batt_mv = 65535.0f; + } + return (uint16_t)batt_mv; +} + +static uint8_t battery_mv_to_percent(uint16_t batt_mv) { + uint16_t empty_mv = runtime_policy_direct_printer_battery_empty_mv(); + uint16_t full_mv = runtime_policy_direct_printer_battery_full_mv(); + if (full_mv <= empty_mv) { + return 100; + } + if (batt_mv <= empty_mv) { + return 0; + } + if (batt_mv >= full_mv) { + return 100; + } + return (uint8_t)(((uint32_t)(batt_mv - empty_mv) * 100u) / (uint32_t)(full_mv - empty_mv)); +} + +static float ntc_raw_to_temp_c(int raw) { + if (raw <= 0 || raw >= ADC_RAW_MAX) { + return 25.0f; + } + + float pullup = (float)runtime_policy_direct_printer_ntc_pullup_ohms(); + float r25 = (float)runtime_policy_direct_printer_ntc_r25_ohms(); + float beta = (float)runtime_policy_direct_printer_ntc_beta(); + if (pullup <= 0.0f || r25 <= 0.0f || beta <= 0.0f) { + return 25.0f; + } + + float ratio = (float)raw / (float)(ADC_RAW_MAX - raw); + float r_ntc = pullup * ratio; + if (r_ntc <= 1.0f) { + return 25.0f; + } + + float inv_t = (1.0f / (273.15f + 25.0f)) + (logf(r_ntc / r25) / beta); + if (inv_t <= 0.0f) { + return 25.0f; + } + return (1.0f / inv_t) - 273.15f; +} + +static void sample_sensors_locked(platform_printer_sensors_t *out_sensors) { + if (out_sensors == NULL) { + return; + } + + memset(out_sensors, 0, sizeof(*out_sensors)); + int paper_level = -1; + out_sensors->has_paper = read_paper_present_locked(&paper_level); + out_sensors->paper_gpio_level = (int8_t)paper_level; + out_sensors->paper_present_level = runtime_policy_direct_printer_paper_present_level(); + out_sensors->battery_percent = 100; + out_sensors->temperature_c = 25.0f; + out_sensors->updated_ms = esp_timer_get_time() / 1000; + + int battery_raw = 0; + if (read_adc_raw_locked(&s_state.battery_adc, &battery_raw) == ESP_OK) { + uint16_t batt_mv = battery_raw_to_mv(battery_raw); + out_sensors->battery_percent = battery_mv_to_percent(batt_mv); + } + + int ntc_raw = 0; + if (read_adc_raw_locked(&s_state.ntc_adc, &ntc_raw) == ESP_OK) { + out_sensors->temperature_c = ntc_raw_to_temp_c(ntc_raw); + } +} + +static esp_err_t precheck_before_print_locked(char *err, size_t err_len) { + platform_printer_sensors_t sensors = {0}; + sample_sensors_locked(&sensors); + + if (!sensors.has_paper) { + write_err(err, err_len, "printer out of paper"); + return ESP_ERR_INVALID_STATE; + } + + float temp_min = runtime_policy_direct_printer_temp_min_c(); + float temp_max = runtime_policy_direct_printer_temp_max_c(); + if (temp_max <= temp_min) { + temp_max = temp_min + 1.0f; + } + if (sensors.temperature_c < temp_min || sensors.temperature_c > temp_max) { + write_err(err, err_len, "temperature out of range"); + return ESP_ERR_INVALID_STATE; + } + + uint8_t battery_min = runtime_policy_direct_printer_battery_min_percent(); + if (sensors.battery_percent < battery_min) { + write_err(err, err_len, "battery too low"); + return ESP_ERR_INVALID_STATE; + } + + return ESP_OK; +} + +static bool has_timed_out(int64_t deadline_ms) { + if (deadline_ms <= 0) { + return false; + } + return (esp_timer_get_time() / 1000) > deadline_ms; +} + +esp_err_t platform_direct_printer_init(void) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + return ESP_ERR_NOT_SUPPORTED; +#else + if (s_state.initialized) { + return ESP_OK; + } + + memset(&s_state, 0, sizeof(s_state)); + s_state.lock = xSemaphoreCreateMutex(); + if (s_state.lock == NULL) { + return ESP_ERR_NO_MEM; + } + set_debug_defaults_locked(); + + esp_err_t err = ESP_OK; + err = config_output_pin(CONFIG_TQ_PRINT_STB_12_PIN, strobe_idle_level_locked(), "print_stb12"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_STB_34_PIN, strobe_idle_level_locked(), "print_stb34"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_STB_56_PIN, strobe_idle_level_locked(), "print_stb56"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_LAT_PIN, 1, "print_lat"); + if (err != ESP_OK) { + return err; + } + err = ensure_shared_shift_pins_gpio_locked(); + if (err != ESP_OK) { + return err; + } + + err = config_output_pin(CONFIG_TQ_PRINT_OUTA_P_PIN, 0, "print_outa_p"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_OUTA_N_PIN, 0, "print_outa_n"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_OUTB_P_PIN, 0, "print_outb_p"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_PRINT_OUTB_N_PIN, 0, "print_outb_n"); + if (err != ESP_OK) { + return err; + } + err = config_output_pin(CONFIG_TQ_KEY_PRINT_PIN, boost_off_level_locked(), "print_boost"); + if (err != ESP_OK) { + return err; + } + + err = config_input_pin(CONFIG_TQ_PRINT_PAPER_PIN, true, "print_paper"); + if (err != ESP_OK) { + return err; + } + + init_adc_pin_if_possible(CONFIG_TQ_BATTERY_ADC_PIN, "battery_adc", &s_state.battery_adc); + init_adc_pin_if_possible(CONFIG_TQ_NTC_ADC_PIN, "ntc_adc", &s_state.ntc_adc); + + s_state.motor_phase = 0; + s_state.connected = false; + s_state.initialized = true; + ESP_LOGI(TAG, "direct printer initialized"); + return ESP_OK; +#endif +} + +void platform_direct_printer_deinit(void) { + if (!s_state.initialized) { + return; + } + + if (s_state.lock != NULL && xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(100)) == pdTRUE) { + safe_drive_off_locked(false); + s_state.connected = false; + xSemaphoreGive(s_state.lock); + } + + if (s_state.adc1_handle != NULL) { + (void)adc_oneshot_del_unit(s_state.adc1_handle); + s_state.adc1_handle = NULL; + } + if (s_state.adc2_handle != NULL) { + (void)adc_oneshot_del_unit(s_state.adc2_handle); + s_state.adc2_handle = NULL; + } + if (s_state.lock != NULL) { + vSemaphoreDelete(s_state.lock); + } + memset(&s_state, 0, sizeof(s_state)); +} + +esp_err_t platform_direct_printer_connect(uint32_t timeout_ms) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + (void)timeout_ms; + return ESP_ERR_NOT_SUPPORTED; +#else + esp_err_t err = platform_direct_printer_init(); + if (err != ESP_OK) { + return err; + } + + uint32_t lock_timeout_ms = timeout_ms == 0 ? 500 : timeout_ms; + if (lock_timeout_ms > 5000) { + lock_timeout_ms = 5000; + } + + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(lock_timeout_ms)) != pdTRUE) { + return ESP_ERR_TIMEOUT; + } + + if (!s_state.connected) { + err = ensure_shared_shift_pins_gpio_locked(); + if (err != ESP_OK) { + xSemaphoreGive(s_state.lock); + return err; + } + set_gpio_level_if_valid(CONFIG_TQ_KEY_PRINT_PIN, boost_on_level_locked()); + vTaskDelay(pdMS_TO_TICKS(10)); + safe_drive_off_locked(true); + s_state.connected = true; + } + + xSemaphoreGive(s_state.lock); + return ESP_OK; +#endif +} + +void platform_direct_printer_disconnect(void) { + if (!s_state.initialized || s_state.lock == NULL) { + return; + } + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(500)) != pdTRUE) { + return; + } + safe_drive_off_locked(false); + s_state.connected = false; + xSemaphoreGive(s_state.lock); +} + +bool platform_direct_printer_is_connected(void) { + if (!s_state.initialized || s_state.lock == NULL) { + return false; + } + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(100)) != pdTRUE) { + return false; + } + bool connected = s_state.connected; + xSemaphoreGive(s_state.lock); + return connected; +} + +esp_err_t platform_direct_printer_get_sensors(platform_printer_sensors_t *out_sensors) { + if (out_sensors == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (!s_state.initialized || s_state.lock == NULL) { + return ESP_ERR_INVALID_STATE; + } + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(500)) != pdTRUE) { + return ESP_ERR_TIMEOUT; + } + sample_sensors_locked(out_sensors); + xSemaphoreGive(s_state.lock); + return ESP_OK; +} + +esp_err_t platform_direct_printer_get_debug_config(uint16_t *out_shift_clock_high_us, + uint16_t *out_shift_clock_low_us, + uint16_t *out_latch_pulse_us, + bool *out_strobe_active_high, + bool *out_boost_active_high, + uint16_t *out_override_strobe_on_us, + uint16_t *out_override_strobe_interval_us, + uint16_t *out_override_motor_step_us, + uint8_t *out_override_steps_per_line) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + (void)out_shift_clock_high_us; + (void)out_shift_clock_low_us; + (void)out_latch_pulse_us; + (void)out_strobe_active_high; + (void)out_boost_active_high; + (void)out_override_strobe_on_us; + (void)out_override_strobe_interval_us; + (void)out_override_motor_step_us; + (void)out_override_steps_per_line; + return ESP_ERR_NOT_SUPPORTED; +#else + if (out_shift_clock_high_us == NULL || out_shift_clock_low_us == NULL || out_latch_pulse_us == NULL || + out_strobe_active_high == NULL || out_boost_active_high == NULL || out_override_strobe_on_us == NULL || + out_override_strobe_interval_us == NULL || out_override_motor_step_us == NULL || + out_override_steps_per_line == NULL) { + return ESP_ERR_INVALID_ARG; + } + esp_err_t init_rc = platform_direct_printer_init(); + if (init_rc != ESP_OK) { + return init_rc; + } + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(500)) != pdTRUE) { + return ESP_ERR_TIMEOUT; + } + *out_shift_clock_high_us = s_state.debug.shift_clock_high_us; + *out_shift_clock_low_us = s_state.debug.shift_clock_low_us; + *out_latch_pulse_us = s_state.debug.latch_pulse_us; + *out_strobe_active_high = s_state.debug.strobe_active_high; + *out_boost_active_high = s_state.debug.boost_active_high; + *out_override_strobe_on_us = s_state.debug.override_strobe_on_us; + *out_override_strobe_interval_us = s_state.debug.override_strobe_interval_us; + *out_override_motor_step_us = s_state.debug.override_motor_step_us; + *out_override_steps_per_line = s_state.debug.override_steps_per_line; + xSemaphoreGive(s_state.lock); + return ESP_OK; +#endif +} + +esp_err_t platform_direct_printer_set_debug_config(bool has_config, + uint16_t shift_clock_high_us, + uint16_t shift_clock_low_us, + uint16_t latch_pulse_us, + bool strobe_active_high, + bool boost_active_high, + uint16_t override_strobe_on_us, + uint16_t override_strobe_interval_us, + uint16_t override_motor_step_us, + uint8_t override_steps_per_line, + bool reset_defaults, + char *err, + size_t err_len) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + (void)has_config; + (void)shift_clock_high_us; + (void)shift_clock_low_us; + (void)latch_pulse_us; + (void)strobe_active_high; + (void)boost_active_high; + (void)override_strobe_on_us; + (void)override_strobe_interval_us; + (void)override_motor_step_us; + (void)override_steps_per_line; + (void)reset_defaults; + write_err(err, err_len, "direct backend disabled"); + return ESP_ERR_NOT_SUPPORTED; +#else + if (!has_config && !reset_defaults) { + write_err(err, err_len, "invalid args"); + return ESP_ERR_INVALID_ARG; + } + + esp_err_t init_rc = platform_direct_printer_init(); + if (init_rc != ESP_OK) { + write_err(err, err_len, "direct backend not initialized"); + return init_rc; + } + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + write_err(err, err_len, "direct printer lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (reset_defaults) { + set_debug_defaults_locked(); + } + + if (has_config) { + if (shift_clock_high_us < DEBUG_SHIFT_CLOCK_US_MIN || shift_clock_high_us > DEBUG_SHIFT_CLOCK_US_MAX || + shift_clock_low_us < DEBUG_SHIFT_CLOCK_US_MIN || shift_clock_low_us > DEBUG_SHIFT_CLOCK_US_MAX) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "shift clock us out of range (1..50)"); + return ESP_ERR_INVALID_ARG; + } + if (latch_pulse_us < DEBUG_LATCH_PULSE_US_MIN || latch_pulse_us > DEBUG_LATCH_PULSE_US_MAX) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "latch pulse us out of range (1..50)"); + return ESP_ERR_INVALID_ARG; + } + if (override_strobe_on_us != 0 && (override_strobe_on_us < 100 || override_strobe_on_us > 10000)) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "strobe_on_us must be 0 or 100..10000"); + return ESP_ERR_INVALID_ARG; + } + if (override_strobe_interval_us > 10000) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "strobe_interval_us must be 0..10000"); + return ESP_ERR_INVALID_ARG; + } + if (override_motor_step_us != 0 && (override_motor_step_us < 100 || override_motor_step_us > 20000)) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "motor_step_us must be 0 or 100..20000"); + return ESP_ERR_INVALID_ARG; + } + if (override_steps_per_line > 8) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "steps_per_line must be 0..8"); + return ESP_ERR_INVALID_ARG; + } + + s_state.debug.shift_clock_high_us = shift_clock_high_us; + s_state.debug.shift_clock_low_us = shift_clock_low_us; + s_state.debug.latch_pulse_us = latch_pulse_us; + s_state.debug.strobe_active_high = strobe_active_high; + s_state.debug.boost_active_high = boost_active_high; + s_state.debug.override_strobe_on_us = override_strobe_on_us; + s_state.debug.override_strobe_interval_us = override_strobe_interval_us; + s_state.debug.override_motor_step_us = override_motor_step_us; + s_state.debug.override_steps_per_line = override_steps_per_line; + } + + safe_drive_off_locked(s_state.connected); + xSemaphoreGive(s_state.lock); + return ESP_OK; +#endif +} + +esp_err_t platform_direct_printer_print(const platform_direct_print_request_t *request, + char *err, + size_t err_len) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + write_err(err, err_len, "direct backend disabled"); + return ESP_ERR_NOT_SUPPORTED; +#else + if (request == NULL || request->raster == NULL || request->width == 0 || request->height == 0) { + write_err(err, err_len, "invalid args"); + return ESP_ERR_INVALID_ARG; + } + if (request->width != 384) { + write_err(err, err_len, "width must be 384"); + return ESP_ERR_INVALID_ARG; + } + + const size_t line_bytes = (size_t)request->width / 8u; + const size_t expected_len = line_bytes * (size_t)request->height; + if (request->raster_len != expected_len) { + write_err(err, err_len, "raster size mismatch"); + return ESP_ERR_INVALID_SIZE; + } + + if (!s_state.initialized || s_state.lock == NULL) { + write_err(err, err_len, "direct backend not initialized"); + return ESP_ERR_INVALID_STATE; + } + + uint32_t timeout_ms = request->timeout_ms; + if (timeout_ms == 0) { + timeout_ms = runtime_policy_direct_printer_operation_timeout_ms(); + } + + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + write_err(err, err_len, "direct printer lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_state.connected) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "direct printer not connected"); + return ESP_ERR_INVALID_STATE; + } + + esp_err_t rc = ensure_shared_shift_pins_gpio_locked(); + if (rc != ESP_OK) { + safe_drive_off_locked(true); + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "direct printer gpio setup failed"); + return rc; + } + + uint16_t strobe_on_us = (request->strobe_on_time_us > 0) + ? request->strobe_on_time_us + : runtime_policy_direct_printer_strobe_on_us(); + uint16_t strobe_interval_us = (request->strobe_interval_us > 0) + ? request->strobe_interval_us + : runtime_policy_direct_printer_strobe_interval_us(); + uint16_t motor_step_us = (request->motor_step_delay_us > 0) + ? request->motor_step_delay_us + : runtime_policy_direct_printer_motor_step_us(); + uint8_t steps_per_line = (request->motor_steps_per_line > 0) + ? request->motor_steps_per_line + : runtime_policy_direct_printer_steps_per_line(); + + if (s_state.debug.override_strobe_on_us > 0) { + strobe_on_us = s_state.debug.override_strobe_on_us; + } + if (s_state.debug.override_strobe_interval_us > 0) { + strobe_interval_us = s_state.debug.override_strobe_interval_us; + } + if (s_state.debug.override_motor_step_us > 0) { + motor_step_us = s_state.debug.override_motor_step_us; + } + if (s_state.debug.override_steps_per_line > 0) { + steps_per_line = s_state.debug.override_steps_per_line; + } + + rc = ESP_OK; + if (!request->ignore_precheck) { + rc = precheck_before_print_locked(err, err_len); + if (rc != ESP_OK) { + safe_drive_off_locked(true); + xSemaphoreGive(s_state.lock); + return rc; + } + } + + int64_t deadline_ms = (int64_t)(esp_timer_get_time() / 1000) + (int64_t)timeout_ms; + + for (uint16_t line = 0; line < request->height; ++line) { + if (request->cancel_flag != NULL && *request->cancel_flag) { + write_err(err, err_len, "job canceled"); + rc = ESP_ERR_INVALID_STATE; + break; + } + if (has_timed_out(deadline_ms)) { + write_err(err, err_len, "print timeout"); + rc = ESP_ERR_TIMEOUT; + break; + } + + if (!request->ignore_precheck && (line & 0x0F) == 0) { + rc = precheck_before_print_locked(err, err_len); + if (rc != ESP_OK) { + break; + } + } + + const uint8_t *line_ptr = &request->raster[(size_t)line * line_bytes]; + write_line_bits_locked(line_ptr, line_bytes); + pulse_latch_locked(); + fire_strobe_locked(strobe_on_us, strobe_interval_us); + + for (uint8_t i = 0; i < steps_per_line; ++i) { + if (request->cancel_flag != NULL && *request->cancel_flag) { + write_err(err, err_len, "job canceled"); + rc = ESP_ERR_INVALID_STATE; + break; + } + if (has_timed_out(deadline_ms)) { + write_err(err, err_len, "print timeout"); + rc = ESP_ERR_TIMEOUT; + break; + } + motor_step_once_locked(motor_step_us); + } + if (rc != ESP_OK) { + break; + } + + // Yield periodically so IDLE task can run and service task WDT on the same CPU. + if (((line + 1u) % k_print_yield_lines) == 0u) { + vTaskDelay(1); + } + } + + safe_drive_off_locked(true); + xSemaphoreGive(s_state.lock); + return rc; +#endif +} + +esp_err_t platform_direct_printer_gap_move(uint32_t timeout_ms, char *err, size_t err_len) { +#if !CONFIG_TQ_DIRECT_PRINTER_ENABLE + write_err(err, err_len, "direct backend disabled"); + return ESP_ERR_NOT_SUPPORTED; +#else + if (!s_state.initialized || s_state.lock == NULL) { + write_err(err, err_len, "direct backend not initialized"); + return ESP_ERR_INVALID_STATE; + } + if (timeout_ms == 0) { + timeout_ms = runtime_policy_direct_printer_operation_timeout_ms(); + } + + if (xSemaphoreTake(s_state.lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + write_err(err, err_len, "direct printer lock timeout"); + return ESP_ERR_TIMEOUT; + } + if (!s_state.connected) { + xSemaphoreGive(s_state.lock); + write_err(err, err_len, "direct printer not connected"); + return ESP_ERR_INVALID_STATE; + } + + esp_err_t rc = ESP_OK; + uint16_t steps = runtime_policy_direct_printer_gap_steps(); + uint16_t step_delay_us = runtime_policy_direct_printer_motor_step_us(); + if (s_state.debug.override_motor_step_us > 0) { + step_delay_us = s_state.debug.override_motor_step_us; + } + platform_printer_sensors_t sensors = {0}; + sample_sensors_locked(&sensors); + + uint8_t battery_min = runtime_policy_direct_printer_battery_min_percent(); + if (sensors.battery_percent < battery_min) { + write_err(err, err_len, "battery too low"); + safe_drive_off_locked(true); + xSemaphoreGive(s_state.lock); + return ESP_ERR_INVALID_STATE; + } + + // Per JX-2R-01 guidance: out-of-paper feed should run at reduced speed (roughly <=600 PPS). + if (!sensors.has_paper && step_delay_us < 1667) { + step_delay_us = 1667; + } + if (!sensors.has_paper) { + ESP_LOGW(TAG, + "gap move while out-of-paper, gpio_level=%d expect=%u step_us=%u", + sensors.paper_gpio_level, + sensors.paper_present_level, + step_delay_us); + } + + int64_t deadline_ms = (int64_t)(esp_timer_get_time() / 1000) + (int64_t)timeout_ms; + + for (uint16_t i = 0; i < steps; ++i) { + if (has_timed_out(deadline_ms)) { + write_err(err, err_len, "gap move timeout"); + rc = ESP_ERR_TIMEOUT; + break; + } + motor_step_once_locked(step_delay_us); + if (((i + 1u) % k_gap_yield_steps) == 0u) { + vTaskDelay(1); + } + } + + safe_drive_off_locked(true); + xSemaphoreGive(s_state.lock); + return rc; +#endif +} diff --git a/components/platform/src/display_lcd_decode_image.c b/components/platform/src/display_lcd_decode_image.c new file mode 100644 index 0000000..25c3eb4 --- /dev/null +++ b/components/platform/src/display_lcd_decode_image.c @@ -0,0 +1,139 @@ +#include "display_lcd_decode_image.h" + +#include +#include +#include +#include + +#include "esp_check.h" +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "lvgl.h" +#include "png.h" + +static const char *TAG = "lcd_png_dec"; + +extern const uint8_t lcd_demo_png_start[] asm("_binary_lcd_demo_png_start"); +extern const uint8_t lcd_demo_png_end[] asm("_binary_lcd_demo_png_end"); + +static void lcd_fill_err(char *err, size_t err_len, const char *msg) +{ + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", msg != NULL ? msg : "unknown"); + } +} + +esp_err_t platform_lcd_decode_png_rgb565(const uint8_t *png, + size_t png_len, + uint16_t **out_pixels, + uint16_t *out_width, + uint16_t *out_height, + char *err, + size_t err_len) +{ + esp_err_t ret = ESP_OK; + + ESP_RETURN_ON_FALSE(out_pixels != NULL && out_width != NULL && out_height != NULL, + ESP_ERR_INVALID_ARG, + TAG, + "invalid output args"); + ESP_RETURN_ON_FALSE(png != NULL && png_len > 0, ESP_ERR_INVALID_ARG, TAG, "invalid png data"); + *out_pixels = NULL; + *out_width = 0; + *out_height = 0; + + png_image image; + memset(&image, 0, sizeof(image)); + image.version = PNG_IMAGE_VERSION; + + if (!png_image_begin_read_from_memory(&image, png, png_len)) { + const char *png_err = image.message[0] != '\0' ? image.message : "png header decode failed"; + lcd_fill_err(err, err_len, png_err); + return ESP_FAIL; + } + ESP_GOTO_ON_FALSE(image.width > 0 && image.height > 0, ESP_ERR_INVALID_SIZE, fail, TAG, "invalid png size"); + ESP_GOTO_ON_FALSE(image.width <= UINT16_MAX && image.height <= UINT16_MAX, + ESP_ERR_INVALID_SIZE, + fail, + TAG, + "png dimensions too large"); + ESP_GOTO_ON_FALSE(image.width <= SIZE_MAX / image.height, ESP_ERR_INVALID_SIZE, fail, TAG, "png too large"); + + image.format = PNG_FORMAT_RGBA; + png_alloc_size_t rgba_size = PNG_IMAGE_SIZE(image); + ESP_GOTO_ON_FALSE(rgba_size > 0, ESP_ERR_INVALID_SIZE, fail, TAG, "png output size invalid"); + + uint8_t *rgba = (uint8_t *)heap_caps_malloc((size_t)rgba_size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (rgba == NULL) { + rgba = (uint8_t *)heap_caps_malloc((size_t)rgba_size, MALLOC_CAP_8BIT); + } + ESP_GOTO_ON_FALSE(rgba != NULL, ESP_ERR_NO_MEM, fail, TAG, "alloc rgba buffer failed"); + + png_alloc_size_t stride = PNG_IMAGE_ROW_STRIDE(image); + if (!png_image_finish_read(&image, NULL, rgba, stride, NULL)) { + const char *png_err = image.message[0] != '\0' ? image.message : "png decode failed"; + lcd_fill_err(err, err_len, png_err); + heap_caps_free(rgba); + png_image_free(&image); + return ESP_FAIL; + } + png_image_free(&image); + + size_t pixel_count = (size_t)image.width * (size_t)image.height; + uint16_t *pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (pixels == NULL) { + pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), MALLOC_CAP_8BIT); + } + if (pixels == NULL) { + lcd_fill_err(err, err_len, "alloc rgb565 buffer failed"); + heap_caps_free(rgba); + return ESP_ERR_NO_MEM; + } + + for (size_t i = 0; i < pixel_count; ++i) { + const size_t base = i * 4u; + uint8_t r = rgba[base]; + uint8_t g = rgba[base + 1u]; + uint8_t b = rgba[base + 2u]; + uint8_t a = rgba[base + 3u]; + if (a < 255u) { + r = (uint8_t)((((uint32_t)r * (uint32_t)a) + (255u * (255u - (uint32_t)a)) + 127u) / 255u); + g = (uint8_t)((((uint32_t)g * (uint32_t)a) + (255u * (255u - (uint32_t)a)) + 127u) / 255u); + b = (uint8_t)((((uint32_t)b * (uint32_t)a) + (255u * (255u - (uint32_t)a)) + 127u) / 255u); + } + lv_color_t color = lv_color_make(r, g, b); + pixels[i] = (uint16_t)color.full; + } + heap_caps_free(rgba); + + *out_pixels = pixels; + *out_width = (uint16_t)image.width; + *out_height = (uint16_t)image.height; + return ESP_OK; + +fail: + lcd_fill_err(err, err_len, "invalid png"); + png_image_free(&image); + if (ret == ESP_OK) { + ret = ESP_FAIL; + } + return ret; +} + +esp_err_t platform_lcd_decode_demo_png(uint16_t **out_pixels, + uint16_t *out_width, + uint16_t *out_height, + char *err, + size_t err_len) +{ + const size_t png_len = (size_t)(lcd_demo_png_end - lcd_demo_png_start); + ESP_RETURN_ON_FALSE(png_len > 0, ESP_ERR_INVALID_SIZE, TAG, "empty png data"); + return platform_lcd_decode_png_rgb565(lcd_demo_png_start, + png_len, + out_pixels, + out_width, + out_height, + err, + err_len); +} diff --git a/components/platform/src/display_lcd_module.c b/components/platform/src/display_lcd_module.c new file mode 100644 index 0000000..b106f52 --- /dev/null +++ b/components/platform/src/display_lcd_module.c @@ -0,0 +1,904 @@ +#include "display_lcd_module.h" + +#include +#include +#include +#include +#include + +#include "esp_check.h" +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" +#include "lvgl.h" +#include "sdkconfig.h" +#include "display_lcd_decode_image.h" +#include "display_st7789p3.h" + +static const char *TAG = "lcd_module"; + +#define ST7789_SPI_HOST SPI2_HOST +#define LCD_PREVIEW_TIMEOUT_MS_DEFAULT 200 +#define LCD_LOCK_TIMEOUT_MS 1000 +#define LCD_DEFAULT_DRAW_LINES 20 +#define LCD_PREVIEW_FADE_DURATION_MS 150 +#define LCD_PREVIEW_FADE_STEPS 3 + +#ifndef CONFIG_TQ_SCREEN_PIXEL_CLOCK_HZ +#define CONFIG_TQ_SCREEN_PIXEL_CLOCK_HZ (10 * 1000 * 1000) +#endif + +#ifndef CONFIG_TQ_SCREEN_H_RES +#define CONFIG_TQ_SCREEN_H_RES 320 +#endif + +#ifndef CONFIG_TQ_SCREEN_V_RES +#define CONFIG_TQ_SCREEN_V_RES 240 +#endif + +#ifndef CONFIG_TQ_SCREEN_SPI_MODE +#define CONFIG_TQ_SCREEN_SPI_MODE 0 +#endif + +#ifndef CONFIG_TQ_SCREEN_DRAW_LINES +#define CONFIG_TQ_SCREEN_DRAW_LINES LCD_DEFAULT_DRAW_LINES +#endif + +#ifndef CONFIG_TQ_SCREEN_COLOR_ORDER_BGR +#define CONFIG_TQ_SCREEN_COLOR_ORDER_BGR 0 +#endif + +#ifndef CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH +#define CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_MIRROR_X +#define CONFIG_TQ_SCREEN_MIRROR_X 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_MIRROR_Y +#define CONFIG_TQ_SCREEN_MIRROR_Y 0 +#endif + +#ifndef CONFIG_TQ_SCREEN_SWAP_XY +#define CONFIG_TQ_SCREEN_SWAP_XY 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_X_GAP +#define CONFIG_TQ_SCREEN_X_GAP 0 +#endif + +#ifndef CONFIG_TQ_SCREEN_Y_GAP +#define CONFIG_TQ_SCREEN_Y_GAP 0 +#endif + +#ifndef CONFIG_TQ_SCREEN_INVERT_COLOR +#define CONFIG_TQ_SCREEN_INVERT_COLOR 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES +#define CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_RESET_PIN +#define CONFIG_TQ_SCREEN_RESET_PIN -1 +#endif + +#ifndef CONFIG_TQ_SCREEN_BACKLIGHT_PIN +#define CONFIG_TQ_SCREEN_BACKLIGHT_PIN -1 +#endif + +#define LCD_PANEL_H_RES ((uint16_t)CONFIG_TQ_SCREEN_H_RES) +#define LCD_PANEL_V_RES ((uint16_t)CONFIG_TQ_SCREEN_V_RES) + +#if CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH +#define ST7789_BACKLIGHT_ON_LEVEL 1 +#else +#define ST7789_BACKLIGHT_ON_LEVEL 0 +#endif + +typedef struct { + st7789p3_handle_t panel; + SemaphoreHandle_t lock; + lv_disp_draw_buf_t lv_draw_buf; + lv_disp_drv_t lv_drv; + lv_disp_t *lv_disp; + lv_obj_t *preview_img; + lv_color_t *draw_buf_1; + lv_color_t *draw_buf_2; + uint16_t *preview_pixels; + lv_img_dsc_t preview_dsc; + bool lvgl_inited; + bool lvgl_ready; + bool initialized; + bool shared_spi_dirty; +} lcd_state_t; + +static lcd_state_t s_lcd; + +void lcd_module_mark_shared_spi_dirty(void) +{ + s_lcd.shared_spi_dirty = true; +} + +static int resolve_reset_pin(void) +{ + if (CONFIG_TQ_SCREEN_RESET_PIN >= 0) { + return CONFIG_TQ_SCREEN_RESET_PIN; + } + return CONFIG_TQ_SCREEN_BACKLIGHT_PIN; +} + +static uint8_t lcd_build_madctl(void) +{ + uint8_t madctl = 0; +#if CONFIG_TQ_SCREEN_MIRROR_X + madctl |= ST7789P3_MADCTL_MX; +#endif +#if CONFIG_TQ_SCREEN_MIRROR_Y + madctl |= ST7789P3_MADCTL_MY; +#endif +#if CONFIG_TQ_SCREEN_SWAP_XY + madctl |= ST7789P3_MADCTL_MV; +#endif +#if CONFIG_TQ_SCREEN_COLOR_ORDER_BGR + madctl |= ST7789P3_MADCTL_BGR; +#endif + return madctl; +} + +static void lcd_fill_err(char *err, size_t err_len, const char *msg) +{ + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", msg != NULL ? msg : "unknown"); + } +} + +static bool lcd_lock_take(uint32_t timeout_ms) +{ + if (s_lcd.lock == NULL) { + return false; + } + TickType_t ticks = pdMS_TO_TICKS(timeout_ms); + if (timeout_ms > 0 && ticks == 0) { + ticks = 1; + } + return xSemaphoreTake(s_lcd.lock, ticks) == pdTRUE; +} + +static void lcd_lock_give(void) +{ + if (s_lcd.lock != NULL) { + xSemaphoreGive(s_lcd.lock); + } +} + +static void *lcd_alloc_fb(size_t bytes) +{ + void *buf = heap_caps_malloc(bytes, MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL); + if (buf == NULL) { + buf = heap_caps_malloc(bytes, MALLOC_CAP_8BIT); + } + return buf; +} + +static void lcd_free_lvgl_buffers(void) +{ + if (s_lcd.draw_buf_1 != NULL) { + heap_caps_free(s_lcd.draw_buf_1); + s_lcd.draw_buf_1 = NULL; + } + if (s_lcd.draw_buf_2 != NULL) { + heap_caps_free(s_lcd.draw_buf_2); + s_lcd.draw_buf_2 = NULL; + } +} + +static esp_err_t lcd_recover_panel_for_shared_spi(void) +{ + if (!s_lcd.initialized || s_lcd.panel == NULL) { + return lcd_module_init(); + } + + if (!s_lcd.shared_spi_dirty) { + return ESP_OK; + } + + /* + * Direct-printer path temporarily takes over shared MOSI/CLK as GPIO. + * Recover LCD SPI routing only when printer touched shared pins. + */ + esp_err_t recover_rc = st7789p3_recover_spi_bus(s_lcd.panel); + if (recover_rc == ESP_OK) { + s_lcd.shared_spi_dirty = false; + return ESP_OK; + } + + ESP_LOGW(TAG, + "fast SPI recover failed: rc=0x%x, fallback to full panel reinit", + (unsigned)recover_rc); + + lcd_module_deinit(); + return lcd_module_init(); +} + +static void lcd_lvgl_flush_cb(lv_disp_drv_t *disp_drv, const lv_area_t *area, lv_color_t *color_map) +{ + st7789p3_handle_t panel = (st7789p3_handle_t)disp_drv->user_data; + if (panel == NULL || area == NULL || color_map == NULL) { + lv_disp_flush_ready(disp_drv); + return; + } + if (area->x1 < 0 || area->y1 < 0 || area->x2 < area->x1 || area->y2 < area->y1) { + lv_disp_flush_ready(disp_drv); + return; + } + + esp_err_t err = st7789p3_draw_bitmap(panel, + (uint16_t)area->x1, + (uint16_t)area->y1, + (uint16_t)(area->x2 + 1), + (uint16_t)(area->y2 + 1), + (const uint16_t *)color_map); + if (err != ESP_OK) { + ESP_LOGW(TAG, "lvgl flush failed: %s", esp_err_to_name(err)); + } + lv_disp_flush_ready(disp_drv); +} + +static esp_err_t lcd_lvgl_init_locked(void) +{ + if (s_lcd.lvgl_ready) { + return ESP_OK; + } + + if (!s_lcd.lvgl_inited) { + lv_init(); + s_lcd.lvgl_inited = true; + } + + const size_t draw_buf_pixels = LCD_PANEL_H_RES * CONFIG_TQ_SCREEN_DRAW_LINES; + const size_t draw_buf_bytes = draw_buf_pixels * sizeof(lv_color_t); + s_lcd.draw_buf_1 = (lv_color_t *)lcd_alloc_fb(draw_buf_bytes); + if (s_lcd.draw_buf_1 == NULL) { + return ESP_ERR_NO_MEM; + } + s_lcd.draw_buf_2 = (lv_color_t *)lcd_alloc_fb(draw_buf_bytes); + if (s_lcd.draw_buf_2 == NULL) { + lcd_free_lvgl_buffers(); + return ESP_ERR_NO_MEM; + } + + lv_disp_draw_buf_init(&s_lcd.lv_draw_buf, s_lcd.draw_buf_1, s_lcd.draw_buf_2, draw_buf_pixels); + + lv_disp_drv_init(&s_lcd.lv_drv); + s_lcd.lv_drv.hor_res = LCD_PANEL_H_RES; + s_lcd.lv_drv.ver_res = LCD_PANEL_V_RES; + s_lcd.lv_drv.flush_cb = lcd_lvgl_flush_cb; + s_lcd.lv_drv.draw_buf = &s_lcd.lv_draw_buf; + s_lcd.lv_drv.user_data = s_lcd.panel; + s_lcd.lv_disp = lv_disp_drv_register(&s_lcd.lv_drv); + if (s_lcd.lv_disp == NULL) { + lcd_free_lvgl_buffers(); + ESP_LOGE(TAG, "lvgl display register failed"); + return ESP_FAIL; + } + + lv_obj_t *screen = lv_scr_act(); + lv_obj_set_style_bg_color(screen, lv_color_black(), LV_PART_MAIN); + lv_obj_set_style_bg_opa(screen, LV_OPA_COVER, LV_PART_MAIN); + lv_obj_clear_flag(screen, LV_OBJ_FLAG_SCROLLABLE); + + s_lcd.preview_img = lv_img_create(screen); + lv_obj_add_flag(s_lcd.preview_img, LV_OBJ_FLAG_HIDDEN); + lv_obj_center(s_lcd.preview_img); + + s_lcd.lvgl_ready = true; + lv_refr_now(s_lcd.lv_disp); + return ESP_OK; +} + +static void lcd_calc_preview_size(uint16_t src_w, uint16_t src_h, uint16_t *out_w, uint16_t *out_h) +{ + if (src_w == 0 || src_h == 0 || out_w == NULL || out_h == NULL) { + return; + } + + if (src_w <= LCD_PANEL_H_RES && src_h <= LCD_PANEL_V_RES) { + *out_w = src_w; + *out_h = src_h; + return; + } + + if ((uint64_t)src_w * LCD_PANEL_V_RES > (uint64_t)src_h * LCD_PANEL_H_RES) { + *out_w = LCD_PANEL_H_RES; + *out_h = (uint16_t)(((uint32_t)src_h * LCD_PANEL_H_RES) / src_w); + } else { + *out_h = LCD_PANEL_V_RES; + *out_w = (uint16_t)(((uint32_t)src_w * LCD_PANEL_V_RES) / src_h); + } + if (*out_w == 0) { + *out_w = 1; + } + if (*out_h == 0) { + *out_h = 1; + } +} + +static esp_err_t lcd_render_raster_to_rgb565(const uint8_t *raster, + size_t raster_len, + uint16_t src_w, + uint16_t src_h, + uint16_t **out_pixels, + uint16_t *out_w, + uint16_t *out_h, + char *err, + size_t err_len) +{ + if (raster == NULL || src_w == 0 || src_h == 0 || out_pixels == NULL || out_w == NULL || out_h == NULL) { + lcd_fill_err(err, err_len, "invalid raster"); + return ESP_ERR_INVALID_ARG; + } + + size_t bytes_per_row = ((size_t)src_w + 7u) / 8u; + size_t needed_len = bytes_per_row * src_h; + if (raster_len < needed_len) { + lcd_fill_err(err, err_len, "raster length mismatch"); + return ESP_ERR_INVALID_SIZE; + } + + lcd_calc_preview_size(src_w, src_h, out_w, out_h); + size_t pixel_count = (size_t)(*out_w) * (size_t)(*out_h); + if (pixel_count == 0 || pixel_count > SIZE_MAX / sizeof(uint16_t)) { + lcd_fill_err(err, err_len, "preview size invalid"); + return ESP_ERR_INVALID_SIZE; + } + + uint16_t *pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (pixels == NULL) { + pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), MALLOC_CAP_8BIT); + } + if (pixels == NULL) { + lcd_fill_err(err, err_len, "no memory"); + return ESP_ERR_NO_MEM; + } + + for (uint16_t y = 0; y < *out_h; ++y) { + uint16_t src_y = (uint16_t)(((uint32_t)y * src_h) / (*out_h)); + size_t row_base = (size_t)src_y * bytes_per_row; + size_t out_row = (size_t)y * (*out_w); + for (uint16_t x = 0; x < *out_w; ++x) { + uint16_t src_x = (uint16_t)(((uint32_t)x * src_w) / (*out_w)); + size_t byte_idx = row_base + (src_x / 8u); + uint8_t bit = (uint8_t)(7u - (src_x % 8u)); + bool is_black = (raster[byte_idx] & (uint8_t)(1u << bit)) != 0; + pixels[out_row + x] = is_black ? 0x0000 : 0xFFFF; + } + } + + *out_pixels = pixels; + return ESP_OK; +} + +static esp_err_t lcd_scale_rgb565_to_preview(const uint16_t *src_pixels, + uint16_t src_w, + uint16_t src_h, + uint16_t **out_pixels, + uint16_t *out_w, + uint16_t *out_h, + char *err, + size_t err_len) +{ + if (src_pixels == NULL || src_w == 0 || src_h == 0 || out_pixels == NULL || out_w == NULL || out_h == NULL) { + lcd_fill_err(err, err_len, "invalid rgb565 image"); + return ESP_ERR_INVALID_ARG; + } + + *out_pixels = NULL; + *out_w = 0; + *out_h = 0; + lcd_calc_preview_size(src_w, src_h, out_w, out_h); + size_t pixel_count = (size_t)(*out_w) * (size_t)(*out_h); + if (pixel_count == 0 || pixel_count > SIZE_MAX / sizeof(uint16_t)) { + lcd_fill_err(err, err_len, "preview size invalid"); + return ESP_ERR_INVALID_SIZE; + } + + uint16_t *preview = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (preview == NULL) { + preview = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), MALLOC_CAP_8BIT); + } + if (preview == NULL) { + lcd_fill_err(err, err_len, "no memory"); + return ESP_ERR_NO_MEM; + } + + if (*out_w == src_w && *out_h == src_h) { + memcpy(preview, src_pixels, pixel_count * sizeof(uint16_t)); + *out_pixels = preview; + return ESP_OK; + } + + for (uint16_t y = 0; y < *out_h; ++y) { + uint16_t src_y = (uint16_t)(((uint32_t)y * src_h) / (*out_h)); + size_t src_row = (size_t)src_y * src_w; + size_t dst_row = (size_t)y * (*out_w); + for (uint16_t x = 0; x < *out_w; ++x) { + uint16_t src_x = (uint16_t)(((uint32_t)x * src_w) / (*out_w)); + preview[dst_row + x] = src_pixels[src_row + src_x]; + } + } + + *out_pixels = preview; + return ESP_OK; +} + +static uint16_t lcd_blend_rgb565(uint16_t from, uint16_t to, uint8_t alpha_255) +{ + uint32_t inv = (uint32_t)(255u - alpha_255); + + uint32_t fr = (from >> 11) & 0x1Fu; + uint32_t fg = (from >> 5) & 0x3Fu; + uint32_t fb = from & 0x1Fu; + + uint32_t tr = (to >> 11) & 0x1Fu; + uint32_t tg = (to >> 5) & 0x3Fu; + uint32_t tb = to & 0x1Fu; + + uint32_t r = (fr * inv + tr * alpha_255 + 127u) / 255u; + uint32_t g = (fg * inv + tg * alpha_255 + 127u) / 255u; + uint32_t b = (fb * inv + tb * alpha_255 + 127u) / 255u; + + return (uint16_t)((r << 11) | (g << 5) | b); +} + +static esp_err_t lcd_draw_preview_pixels_locked(const uint16_t *pixels, + uint16_t preview_w, + uint16_t preview_h, + char *err, + size_t err_len) +{ + if (s_lcd.panel == NULL || pixels == NULL) { + lcd_fill_err(err, err_len, "display panel not ready"); + return ESP_ERR_INVALID_STATE; + } + if (preview_w == 0 || preview_h == 0 || preview_w > LCD_PANEL_H_RES || preview_h > LCD_PANEL_V_RES) { + lcd_fill_err(err, err_len, "invalid preview size"); + return ESP_ERR_INVALID_SIZE; + } + + uint16_t x = (uint16_t)((LCD_PANEL_H_RES - preview_w) / 2u); + uint16_t y = (uint16_t)((LCD_PANEL_V_RES - preview_h) / 2u); + esp_err_t draw_rc = st7789p3_draw_bitmap(s_lcd.panel, + x, + y, + (uint16_t)(x + preview_w), + (uint16_t)(y + preview_h), + pixels); + if (draw_rc != ESP_OK) { + lcd_fill_err(err, err_len, "display draw failed"); + return draw_rc; + } + return ESP_OK; +} + +static esp_err_t lcd_apply_preview_locked(const uint16_t *prev_pixels, + uint16_t prev_w, + uint16_t prev_h, + bool clear_before_draw, + lv_color_t bg_color, + char *err, + size_t err_len) +{ + if (s_lcd.panel == NULL || s_lcd.preview_pixels == NULL) { + lcd_fill_err(err, err_len, "display panel not ready"); + return ESP_ERR_INVALID_STATE; + } + + uint16_t preview_w = s_lcd.preview_dsc.header.w; + uint16_t preview_h = s_lcd.preview_dsc.header.h; + if (preview_w == 0 || preview_h == 0 || preview_w > LCD_PANEL_H_RES || preview_h > LCD_PANEL_V_RES) { + lcd_fill_err(err, err_len, "invalid preview size"); + return ESP_ERR_INVALID_SIZE; + } + + if (clear_before_draw) { + esp_err_t clear_rc = st7789p3_fill_color(s_lcd.panel, (uint16_t)bg_color.full); + if (clear_rc != ESP_OK) { + lcd_fill_err(err, err_len, "display clear failed"); + return clear_rc; + } + esp_err_t draw_rc = lcd_draw_preview_pixels_locked(s_lcd.preview_pixels, preview_w, preview_h, err, err_len); + if (draw_rc == ESP_OK) { + ESP_LOGI(TAG, "preview drawn directly: size=%ux%u", (unsigned)preview_w, (unsigned)preview_h); + } + return draw_rc; + } + + bool can_fade = (prev_pixels != NULL && prev_w == preview_w && prev_h == preview_h); + if (!can_fade) { + esp_err_t draw_rc = lcd_draw_preview_pixels_locked(s_lcd.preview_pixels, preview_w, preview_h, err, err_len); + if (draw_rc == ESP_OK) { + ESP_LOGI(TAG, "preview drawn directly: size=%ux%u", (unsigned)preview_w, (unsigned)preview_h); + } + return draw_rc; + } + + size_t pixel_count = (size_t)preview_w * (size_t)preview_h; + uint16_t *fade_pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), + MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (fade_pixels == NULL) { + fade_pixels = (uint16_t *)heap_caps_malloc(pixel_count * sizeof(uint16_t), MALLOC_CAP_8BIT); + } + if (fade_pixels == NULL) { + // Fallback to direct draw when memory is tight. + esp_err_t draw_rc = lcd_draw_preview_pixels_locked(s_lcd.preview_pixels, preview_w, preview_h, err, err_len); + if (draw_rc == ESP_OK) { + ESP_LOGI(TAG, "preview drawn directly (fade fallback): size=%ux%u", (unsigned)preview_w, (unsigned)preview_h); + } + return draw_rc; + } + + const uint32_t frame_count = LCD_PREVIEW_FADE_STEPS + 1u; + uint32_t frame_delay_ms = LCD_PREVIEW_FADE_DURATION_MS / frame_count; + if (frame_delay_ms == 0) { + frame_delay_ms = 1; + } + + for (uint32_t step = 1; step <= LCD_PREVIEW_FADE_STEPS; ++step) { + uint8_t alpha = (uint8_t)((step * 255u) / frame_count); + for (size_t i = 0; i < pixel_count; ++i) { + fade_pixels[i] = lcd_blend_rgb565(prev_pixels[i], s_lcd.preview_pixels[i], alpha); + } + + esp_err_t draw_rc = lcd_draw_preview_pixels_locked(fade_pixels, preview_w, preview_h, err, err_len); + if (draw_rc != ESP_OK) { + heap_caps_free(fade_pixels); + return draw_rc; + } + vTaskDelay(pdMS_TO_TICKS(frame_delay_ms)); + } + + heap_caps_free(fade_pixels); + esp_err_t draw_rc = lcd_draw_preview_pixels_locked(s_lcd.preview_pixels, preview_w, preview_h, err, err_len); + if (draw_rc == ESP_OK) { + ESP_LOGI(TAG, "preview drawn with fade: size=%ux%u fade_ms=%u", + (unsigned)preview_w, + (unsigned)preview_h, + (unsigned)LCD_PREVIEW_FADE_DURATION_MS); + } + return draw_rc; +} + +void lcd_module_deinit(void) +{ +#if CONFIG_TQ_SCREEN_ENABLE + if (s_lcd.lock != NULL) { + if (xSemaphoreTake(s_lcd.lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + return; + } + } + + if (s_lcd.lv_disp != NULL) { + lv_disp_remove(s_lcd.lv_disp); + s_lcd.lv_disp = NULL; + } + if (s_lcd.preview_pixels != NULL) { + heap_caps_free(s_lcd.preview_pixels); + s_lcd.preview_pixels = NULL; + } + lcd_free_lvgl_buffers(); + s_lcd.preview_img = NULL; + s_lcd.lvgl_ready = false; + + if (s_lcd.lock != NULL) { + xSemaphoreGive(s_lcd.lock); + vSemaphoreDelete(s_lcd.lock); + s_lcd.lock = NULL; + } + + if (s_lcd.panel != NULL) { + (void)st7789p3_del(s_lcd.panel); + s_lcd.panel = NULL; + } + s_lcd.initialized = false; +#endif +} + +esp_err_t lcd_module_init(void) +{ +#if !CONFIG_TQ_SCREEN_ENABLE + return ESP_ERR_NOT_SUPPORTED; +#else + if (s_lcd.initialized) { + return ESP_OK; + } + + st7789p3_config_t lcd_cfg = ST7789P3_CONFIG_DEFAULT(); + lcd_cfg.spi_host = ST7789_SPI_HOST; + lcd_cfg.pin_miso = CONFIG_TQ_PRINTER_MISO_PIN; + lcd_cfg.pin_mosi = CONFIG_TQ_SPI_SHARED_MOSI_PIN; + lcd_cfg.pin_sclk = CONFIG_TQ_SPI_SHARED_CLK_PIN; + lcd_cfg.pin_cs = CONFIG_TQ_SCREEN_CS_PIN; + lcd_cfg.pin_dc = CONFIG_TQ_SCREEN_DC_PIN; + lcd_cfg.pin_rst = resolve_reset_pin(); + lcd_cfg.pin_bckl = CONFIG_TQ_SCREEN_BACKLIGHT_PIN; + lcd_cfg.backlight_on_level = ST7789_BACKLIGHT_ON_LEVEL; + lcd_cfg.pclk_hz = CONFIG_TQ_SCREEN_PIXEL_CLOCK_HZ; + lcd_cfg.spi_mode = CONFIG_TQ_SCREEN_SPI_MODE; + lcd_cfg.h_res = LCD_PANEL_H_RES; + lcd_cfg.v_res = LCD_PANEL_V_RES; + lcd_cfg.x_gap = (uint16_t)CONFIG_TQ_SCREEN_X_GAP; + lcd_cfg.y_gap = (uint16_t)CONFIG_TQ_SCREEN_Y_GAP; + lcd_cfg.madctl_val = lcd_build_madctl(); + lcd_cfg.invert_color = CONFIG_TQ_SCREEN_INVERT_COLOR; + lcd_cfg.swap_color_bytes = CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES; + lcd_cfg.max_transfer_sz = CONFIG_TQ_SCREEN_DRAW_LINES * LCD_PANEL_H_RES * sizeof(uint16_t) + 8; + + esp_err_t err = st7789p3_new_panel(&lcd_cfg, &s_lcd.panel); + if (err != ESP_OK) { + return err; + } + + err = st7789p3_init(s_lcd.panel); + if (err != ESP_OK) { + lcd_module_deinit(); + return err; + } + + s_lcd.lock = xSemaphoreCreateMutex(); + if (s_lcd.lock == NULL) { + lcd_module_deinit(); + return ESP_ERR_NO_MEM; + } + + if (!lcd_lock_take(LCD_LOCK_TIMEOUT_MS)) { + lcd_module_deinit(); + return ESP_ERR_TIMEOUT; + } + err = lcd_lvgl_init_locked(); + lcd_lock_give(); + if (err != ESP_OK) { + lcd_module_deinit(); + return err; + } + + s_lcd.initialized = true; + s_lcd.shared_spi_dirty = false; + ESP_LOGI(TAG, + "st7789p3 ready: spi_host=%d mosi=%d clk=%d miso=%d dc=%d cs=%d rst=%d bk=%d pclk=%u mode=%u res=%ux%u madctl=0x%02x gap=%u,%u invert=%d swap_bytes=%d", + ST7789_SPI_HOST, + CONFIG_TQ_SPI_SHARED_MOSI_PIN, + CONFIG_TQ_SPI_SHARED_CLK_PIN, + CONFIG_TQ_PRINTER_MISO_PIN, + CONFIG_TQ_SCREEN_DC_PIN, + CONFIG_TQ_SCREEN_CS_PIN, + lcd_cfg.pin_rst, + CONFIG_TQ_SCREEN_BACKLIGHT_PIN, + (unsigned)lcd_cfg.pclk_hz, + (unsigned)lcd_cfg.spi_mode, + (unsigned)lcd_cfg.h_res, + (unsigned)lcd_cfg.v_res, + (unsigned)lcd_cfg.madctl_val, + (unsigned)lcd_cfg.x_gap, + (unsigned)lcd_cfg.y_gap, + lcd_cfg.invert_color ? 1 : 0, + lcd_cfg.swap_color_bytes ? 1 : 0); + return ESP_OK; +#endif +} + +esp_err_t lcd_module_show_raster_1bpp(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ +#if !CONFIG_TQ_SCREEN_ENABLE + return ESP_ERR_NOT_SUPPORTED; +#else + ESP_RETURN_ON_ERROR(lcd_recover_panel_for_shared_spi(), TAG, "display init failed"); + + if (timeout_ms == 0) { + timeout_ms = LCD_PREVIEW_TIMEOUT_MS_DEFAULT; + } + + uint16_t *preview_pixels = NULL; + uint16_t preview_w = 0; + uint16_t preview_h = 0; + esp_err_t convert_err = lcd_render_raster_to_rgb565(raster, + raster_len, + width, + height, + &preview_pixels, + &preview_w, + &preview_h, + err, + err_len); + if (convert_err != ESP_OK) { + return convert_err; + } + + if (!lcd_lock_take(timeout_ms)) { + heap_caps_free(preview_pixels); + lcd_fill_err(err, err_len, "display lock timeout"); + return ESP_ERR_TIMEOUT; + } + + uint16_t *prev_pixels = s_lcd.preview_pixels; + uint16_t prev_w = s_lcd.preview_dsc.header.w; + uint16_t prev_h = s_lcd.preview_dsc.header.h; + bool clear_before_draw = (s_lcd.preview_pixels == NULL || + s_lcd.preview_dsc.header.w != preview_w || + s_lcd.preview_dsc.header.h != preview_h); + s_lcd.preview_pixels = preview_pixels; + + memset(&s_lcd.preview_dsc, 0, sizeof(s_lcd.preview_dsc)); + s_lcd.preview_dsc.header.always_zero = 0; + s_lcd.preview_dsc.header.w = preview_w; + s_lcd.preview_dsc.header.h = preview_h; + s_lcd.preview_dsc.header.cf = LV_IMG_CF_TRUE_COLOR; + s_lcd.preview_dsc.data_size = (uint32_t)((size_t)preview_w * preview_h * sizeof(uint16_t)); + s_lcd.preview_dsc.data = (const uint8_t *)s_lcd.preview_pixels; + + esp_err_t draw_err = lcd_apply_preview_locked(prev_pixels, + prev_w, + prev_h, + clear_before_draw, + lv_color_white(), + err, + err_len); + if (prev_pixels != NULL) { + heap_caps_free(prev_pixels); + } + lcd_lock_give(); + return draw_err; +#endif +} + +esp_err_t lcd_module_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ +#if !CONFIG_TQ_SCREEN_ENABLE + return ESP_ERR_NOT_SUPPORTED; +#else + ESP_RETURN_ON_ERROR(lcd_recover_panel_for_shared_spi(), TAG, "display init failed"); + + if (timeout_ms == 0) { + timeout_ms = LCD_PREVIEW_TIMEOUT_MS_DEFAULT; + } + + uint16_t *src_pixels = NULL; + uint16_t src_w = 0; + uint16_t src_h = 0; + esp_err_t decode_err = platform_lcd_decode_png_rgb565(png, + png_len, + &src_pixels, + &src_w, + &src_h, + err, + err_len); + if (decode_err != ESP_OK) { + return decode_err; + } + + uint16_t *preview_pixels = NULL; + uint16_t preview_w = 0; + uint16_t preview_h = 0; + esp_err_t scale_err = lcd_scale_rgb565_to_preview(src_pixels, + src_w, + src_h, + &preview_pixels, + &preview_w, + &preview_h, + err, + err_len); + heap_caps_free(src_pixels); + if (scale_err != ESP_OK) { + return scale_err; + } + + if (!lcd_lock_take(timeout_ms)) { + heap_caps_free(preview_pixels); + lcd_fill_err(err, err_len, "display lock timeout"); + return ESP_ERR_TIMEOUT; + } + + uint16_t *prev_pixels = s_lcd.preview_pixels; + uint16_t prev_w = s_lcd.preview_dsc.header.w; + uint16_t prev_h = s_lcd.preview_dsc.header.h; + bool clear_before_draw = (s_lcd.preview_pixels == NULL || + s_lcd.preview_dsc.header.w != preview_w || + s_lcd.preview_dsc.header.h != preview_h); + s_lcd.preview_pixels = preview_pixels; + + memset(&s_lcd.preview_dsc, 0, sizeof(s_lcd.preview_dsc)); + s_lcd.preview_dsc.header.always_zero = 0; + s_lcd.preview_dsc.header.w = preview_w; + s_lcd.preview_dsc.header.h = preview_h; + s_lcd.preview_dsc.header.cf = LV_IMG_CF_TRUE_COLOR; + s_lcd.preview_dsc.data_size = (uint32_t)((size_t)preview_w * preview_h * sizeof(uint16_t)); + s_lcd.preview_dsc.data = (const uint8_t *)s_lcd.preview_pixels; + + esp_err_t draw_err = lcd_apply_preview_locked(prev_pixels, + prev_w, + prev_h, + clear_before_draw, + lv_color_white(), + err, + err_len); + if (prev_pixels != NULL) { + heap_caps_free(prev_pixels); + } + lcd_lock_give(); + return draw_err; +#endif +} + +esp_err_t lcd_module_start_demo(void) +{ +#if !CONFIG_TQ_SCREEN_ENABLE + return ESP_ERR_NOT_SUPPORTED; +#else + ESP_RETURN_ON_ERROR(lcd_recover_panel_for_shared_spi(), TAG, "display init failed"); + if (!lcd_lock_take(LCD_LOCK_TIMEOUT_MS)) { + return ESP_ERR_TIMEOUT; + } + + uint16_t *demo_pixels = NULL; + uint16_t demo_w = 0; + uint16_t demo_h = 0; + char decode_err[96] = {0}; + esp_err_t decode_rc = platform_lcd_decode_demo_png(&demo_pixels, + &demo_w, + &demo_h, + decode_err, + sizeof(decode_err)); + if (decode_rc != ESP_OK) { + ESP_LOGW(TAG, "demo png decode failed: rc=0x%x msg=%s", (unsigned)decode_rc, decode_err); + lcd_lock_give(); + return decode_rc; + } + + uint16_t *prev_pixels = s_lcd.preview_pixels; + uint16_t prev_w = s_lcd.preview_dsc.header.w; + uint16_t prev_h = s_lcd.preview_dsc.header.h; + bool clear_before_draw = (s_lcd.preview_pixels == NULL || + s_lcd.preview_dsc.header.w != demo_w || + s_lcd.preview_dsc.header.h != demo_h); + s_lcd.preview_pixels = demo_pixels; + + memset(&s_lcd.preview_dsc, 0, sizeof(s_lcd.preview_dsc)); + s_lcd.preview_dsc.header.always_zero = 0; + s_lcd.preview_dsc.header.w = demo_w; + s_lcd.preview_dsc.header.h = demo_h; + s_lcd.preview_dsc.header.cf = LV_IMG_CF_TRUE_COLOR; + s_lcd.preview_dsc.data_size = (uint32_t)((size_t)demo_w * demo_h * sizeof(uint16_t)); + s_lcd.preview_dsc.data = (const uint8_t *)s_lcd.preview_pixels; + + esp_err_t draw_err = lcd_apply_preview_locked(prev_pixels, + prev_w, + prev_h, + clear_before_draw, + lv_color_black(), + decode_err, + sizeof(decode_err)); + if (prev_pixels != NULL) { + heap_caps_free(prev_pixels); + } + lcd_lock_give(); + if (draw_err != ESP_OK) { + ESP_LOGW(TAG, "demo draw failed: rc=0x%x msg=%s", (unsigned)draw_err, decode_err); + return draw_err; + } + return ESP_OK; +#endif +} diff --git a/components/platform/src/display_st7789.c b/components/platform/src/display_st7789.c new file mode 100644 index 0000000..88ff964 --- /dev/null +++ b/components/platform/src/display_st7789.c @@ -0,0 +1,43 @@ +#include "platform.h" + +#include "display_lcd_module.h" + +void platform_display_deinit(void) +{ + lcd_module_deinit(); +} + +esp_err_t platform_display_init(void) +{ + return lcd_module_init(); +} + +esp_err_t platform_display_show_test_pattern(void) +{ + return lcd_module_start_demo(); +} + +esp_err_t platform_display_show_raster_1bpp(const uint8_t *raster, + size_t raster_len, + uint16_t width, + uint16_t height, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ + return lcd_module_show_raster_1bpp(raster, raster_len, width, height, timeout_ms, err, err_len); +} + +esp_err_t platform_display_show_png(const uint8_t *png, + size_t png_len, + uint32_t timeout_ms, + char *err, + size_t err_len) +{ + return lcd_module_show_png(png, png_len, timeout_ms, err, err_len); +} + +void platform_display_mark_shared_spi_dirty(void) +{ + lcd_module_mark_shared_spi_dirty(); +} diff --git a/components/platform/src/display_st7789p3.c b/components/platform/src/display_st7789p3.c new file mode 100644 index 0000000..09aec65 --- /dev/null +++ b/components/platform/src/display_st7789p3.c @@ -0,0 +1,575 @@ +#include "display_st7789p3.h" + +#include +#include + +#include "driver/gpio.h" +#include "esp_attr.h" +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" + +#define ST7789P3_CMD_DELAY_FLAG 0x80 +#define ST7789P3_CMD_DATA_LEN_MASK 0x1F +#define ST7789P3_TX_MAX_CHUNK_BYTES 1024 +#define ST7789P3_SWAP_BUF_PIXELS 256 + +typedef struct { + uint8_t cmd; + uint8_t data[16]; + uint8_t data_bytes; +} st7789p3_lcd_init_cmd_t; + +struct st7789p3_panel_t { + st7789p3_config_t cfg; + spi_device_handle_t spi; + bool bus_owned; +}; + +static const char *TAG = "st7789p3"; + +// Sequence verified on the LCD used by docs/lcd_verification. +DRAM_ATTR static const st7789p3_lcd_init_cmd_t s_st7789p3_init_cmds[] = { + {0x36, {0x00}, 1}, + {0x3A, {0x55}, 1}, + {0xB2, {0x0C, 0x0C, 0x00, 0x33, 0x33}, 5}, + {0xB7, {0x45}, 1}, + {0xBB, {0x2B}, 1}, + {0xC0, {0x2C}, 1}, + {0xC2, {0x01, 0xFF}, 2}, + {0xC3, {0x11}, 1}, + {0xC4, {0x20}, 1}, + {0xC6, {0x0F}, 1}, + {0xD0, {0xA4, 0xA1}, 2}, + {0xE0, {0xD0, 0x00, 0x05, 0x0E, 0x15, 0x0D, 0x37, 0x43, 0x47, 0x09, 0x15, 0x12, 0x16, 0x19}, 14}, + {0xE1, {0xD0, 0x00, 0x05, 0x0D, 0x0C, 0x06, 0x2D, 0x44, 0x40, 0x0E, 0x1C, 0x18, 0x16, 0x19}, 14}, + {0x11, {0}, ST7789P3_CMD_DELAY_FLAG}, + {0, {0}, 0xFF}, +}; + +static esp_err_t st7789p3_validate_config(const st7789p3_config_t *config) +{ + if (config == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (config->pin_mosi < 0 || config->pin_sclk < 0 || config->pin_cs < 0 || config->pin_dc < 0) { + return ESP_ERR_INVALID_ARG; + } + if (config->h_res == 0 || config->v_res == 0) { + return ESP_ERR_INVALID_ARG; + } + if (config->spi_mode > 3) { + return ESP_ERR_INVALID_ARG; + } + return ESP_OK; +} + +static esp_err_t st7789p3_configure_gpio(st7789p3_handle_t panel) +{ + uint64_t pin_mask = 0; + + pin_mask |= (1ULL << panel->cfg.pin_dc); + if (panel->cfg.pin_rst >= 0) { + pin_mask |= (1ULL << panel->cfg.pin_rst); + } + if (panel->cfg.pin_bckl >= 0) { + pin_mask |= (1ULL << panel->cfg.pin_bckl); + } + + gpio_config_t io_conf = { + .pin_bit_mask = pin_mask, + .mode = GPIO_MODE_OUTPUT, + .pull_up_en = GPIO_PULLUP_DISABLE, + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .intr_type = GPIO_INTR_DISABLE, + }; + + return gpio_config(&io_conf); +} + +static esp_err_t st7789p3_spi_write(st7789p3_handle_t panel, int dc_level, const void *data, size_t data_size) +{ + if (data_size == 0) { + return ESP_OK; + } + + esp_err_t ret = gpio_set_level(panel->cfg.pin_dc, dc_level); + if (ret != ESP_OK) { + return ret; + } + + spi_transaction_t t = {0}; + t.length = data_size * 8; + t.tx_buffer = data; + + return spi_device_transmit(panel->spi, &t); +} + +static esp_err_t st7789p3_send_cmd(st7789p3_handle_t panel, uint8_t cmd) +{ + return st7789p3_spi_write(panel, 0, &cmd, 1); +} + +static esp_err_t st7789p3_send_data(st7789p3_handle_t panel, const void *data, size_t data_size) +{ + const uint8_t *data_ptr = (const uint8_t *)data; + size_t remaining = data_size; + size_t tx_chunk_size = ST7789P3_TX_MAX_CHUNK_BYTES; + + if (panel->cfg.max_transfer_sz > 0 && panel->cfg.max_transfer_sz < tx_chunk_size) { + tx_chunk_size = panel->cfg.max_transfer_sz; + } + + while (remaining > 0) { + size_t chunk = (remaining > tx_chunk_size) ? tx_chunk_size : remaining; + esp_err_t ret = st7789p3_spi_write(panel, 1, data_ptr, chunk); + if (ret != ESP_OK) { + return ret; + } + data_ptr += chunk; + remaining -= chunk; + } + return ESP_OK; +} + +static esp_err_t st7789p3_send_color_data(st7789p3_handle_t panel, const uint16_t *color_data, size_t pixel_count) +{ + if (color_data == NULL || pixel_count == 0) { + return ESP_OK; + } + + if (!panel->cfg.swap_color_bytes) { + return st7789p3_send_data(panel, color_data, pixel_count * sizeof(uint16_t)); + } + + uint8_t swap_buf[ST7789P3_SWAP_BUF_PIXELS * sizeof(uint16_t)]; + size_t offset = 0; + while (offset < pixel_count) { + size_t chunk = pixel_count - offset; + if (chunk > ST7789P3_SWAP_BUF_PIXELS) { + chunk = ST7789P3_SWAP_BUF_PIXELS; + } + + for (size_t i = 0; i < chunk; ++i) { + uint16_t color = color_data[offset + i]; + swap_buf[i * 2] = (uint8_t)(color >> 8); + swap_buf[i * 2 + 1] = (uint8_t)(color & 0xFF); + } + + esp_err_t ret = st7789p3_spi_write(panel, 1, swap_buf, chunk * sizeof(uint16_t)); + if (ret != ESP_OK) { + return ret; + } + offset += chunk; + } + + return ESP_OK; +} + +static esp_err_t st7789p3_run_init_cmds(st7789p3_handle_t panel) +{ + for (size_t i = 0; s_st7789p3_init_cmds[i].data_bytes != 0xFF; i++) { + const st7789p3_lcd_init_cmd_t *init_cmd = &s_st7789p3_init_cmds[i]; + uint8_t data_bytes = init_cmd->data_bytes & ST7789P3_CMD_DATA_LEN_MASK; + uint8_t data[16] = {0}; + + if (data_bytes > 0) { + memcpy(data, init_cmd->data, data_bytes); + } + + if (init_cmd->cmd == 0x36 && data_bytes == 1) { + data[0] = panel->cfg.madctl_val; + } + + esp_err_t ret = st7789p3_send_cmd(panel, init_cmd->cmd); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_send_data(panel, data, data_bytes); + if (ret != ESP_OK) { + return ret; + } + + if (init_cmd->data_bytes & ST7789P3_CMD_DELAY_FLAG) { + vTaskDelay(pdMS_TO_TICKS(100)); + } + } + return ESP_OK; +} + +static esp_err_t st7789p3_attach_spi_device(st7789p3_handle_t panel) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + if (panel->cfg.init_spi_bus) { + spi_bus_config_t buscfg = { + .mosi_io_num = panel->cfg.pin_mosi, + .miso_io_num = panel->cfg.pin_miso, + .sclk_io_num = panel->cfg.pin_sclk, + .quadwp_io_num = -1, + .quadhd_io_num = -1, + .max_transfer_sz = panel->cfg.max_transfer_sz, + }; + + esp_err_t ret = spi_bus_initialize(panel->cfg.spi_host, &buscfg, SPI_DMA_CH_AUTO); + if (ret == ESP_OK) { + panel->bus_owned = true; + } else if (ret == ESP_ERR_INVALID_STATE) { + panel->bus_owned = false; + ESP_LOGW(TAG, "SPI host already initialized, skip bus init"); + } else { + return ret; + } + } else { + panel->bus_owned = false; + } + + spi_device_interface_config_t devcfg = { + .clock_speed_hz = panel->cfg.pclk_hz, + .mode = panel->cfg.spi_mode, + .spics_io_num = panel->cfg.pin_cs, + .queue_size = panel->cfg.queue_size, + }; + + esp_err_t ret = spi_bus_add_device(panel->cfg.spi_host, &devcfg, &panel->spi); + if (ret != ESP_OK) { + if (panel->bus_owned) { + (void)spi_bus_free(panel->cfg.spi_host); + panel->bus_owned = false; + } + return ret; + } + return ESP_OK; +} + +esp_err_t st7789p3_new_panel(const st7789p3_config_t *config, st7789p3_handle_t *ret_panel) +{ + if (ret_panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + *ret_panel = NULL; + + esp_err_t ret = st7789p3_validate_config(config); + if (ret != ESP_OK) { + return ret; + } + + st7789p3_handle_t panel = calloc(1, sizeof(*panel)); + if (panel == NULL) { + return ESP_ERR_NO_MEM; + } + + panel->cfg = *config; + if (panel->cfg.pclk_hz == 0) { + panel->cfg.pclk_hz = 10 * 1000 * 1000; + } + if (panel->cfg.queue_size <= 0) { + panel->cfg.queue_size = 7; + } + if (panel->cfg.max_transfer_sz == 0) { + panel->cfg.max_transfer_sz = panel->cfg.h_res * 20 * sizeof(uint16_t) + 8; + } + + ret = st7789p3_configure_gpio(panel); + if (ret != ESP_OK) { + free(panel); + return ret; + } + + ret = st7789p3_attach_spi_device(panel); + if (ret != ESP_OK) { + free(panel); + return ret; + } + + *ret_panel = panel; + return ESP_OK; +} + +esp_err_t st7789p3_del(st7789p3_handle_t panel) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + esp_err_t ret = ESP_OK; + esp_err_t local_ret = spi_bus_remove_device(panel->spi); + if (local_ret != ESP_OK) { + ret = local_ret; + } + + if (panel->bus_owned) { + local_ret = spi_bus_free(panel->cfg.spi_host); + if (ret == ESP_OK && local_ret != ESP_OK) { + ret = local_ret; + } + } + + free(panel); + return ret; +} + +esp_err_t st7789p3_recover_spi_bus(st7789p3_handle_t panel) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + esp_err_t ret = st7789p3_configure_gpio(panel); + if (ret != ESP_OK) { + return ret; + } + + if (panel->spi != NULL) { + ret = spi_bus_remove_device(panel->spi); + if (ret != ESP_OK) { + return ret; + } + panel->spi = NULL; + } + + if (panel->bus_owned) { + ret = spi_bus_free(panel->cfg.spi_host); + if (ret != ESP_OK) { + return ret; + } + panel->bus_owned = false; + } + + ret = st7789p3_attach_spi_device(panel); + if (ret != ESP_OK) { + return ret; + } + + // Keep current frame on panel; just ensure display state remains on. + return st7789p3_send_cmd(panel, 0x29); +} + +esp_err_t st7789p3_set_backlight(st7789p3_handle_t panel, bool on) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (panel->cfg.pin_bckl < 0) { + return ESP_OK; + } + + int on_level = panel->cfg.backlight_on_level ? 1 : 0; + int off_level = on_level ? 0 : 1; + return gpio_set_level(panel->cfg.pin_bckl, on ? on_level : off_level); +} + +esp_err_t st7789p3_set_madctl(st7789p3_handle_t panel, uint8_t madctl_val) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + panel->cfg.madctl_val = madctl_val; + esp_err_t ret = st7789p3_send_cmd(panel, 0x36); + if (ret != ESP_OK) { + return ret; + } + return st7789p3_send_data(panel, &madctl_val, 1); +} + +esp_err_t st7789p3_set_invert(st7789p3_handle_t panel, bool invert_color) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + panel->cfg.invert_color = invert_color; + return st7789p3_send_cmd(panel, invert_color ? 0x21 : 0x20); +} + +esp_err_t st7789p3_set_swap_color_bytes(st7789p3_handle_t panel, bool swap_color_bytes) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + panel->cfg.swap_color_bytes = swap_color_bytes; + return ESP_OK; +} + +esp_err_t st7789p3_reset(st7789p3_handle_t panel) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + if (panel->cfg.pin_rst < 0) { + return ESP_OK; + } + + esp_err_t ret = gpio_set_level(panel->cfg.pin_rst, 0); + if (ret != ESP_OK) { + return ret; + } + vTaskDelay(pdMS_TO_TICKS(100)); + + ret = gpio_set_level(panel->cfg.pin_rst, 1); + if (ret != ESP_OK) { + return ret; + } + vTaskDelay(pdMS_TO_TICKS(100)); + return ESP_OK; +} + +esp_err_t st7789p3_init(st7789p3_handle_t panel) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + esp_err_t ret = st7789p3_set_backlight(panel, false); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_reset(panel); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_run_init_cmds(panel); + if (ret != ESP_OK) { + return ret; + } + + // Re-assert MADCTL after init sequence while backlight is still off, + // to avoid a visible first-frame transition on some panels. + ret = st7789p3_set_madctl(panel, panel->cfg.madctl_val); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_set_invert(panel, panel->cfg.invert_color); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_send_cmd(panel, 0x29); + if (ret != ESP_OK) { + return ret; + } + vTaskDelay(pdMS_TO_TICKS(100)); + + return st7789p3_set_backlight(panel, true); +} + +esp_err_t st7789p3_set_window( + st7789p3_handle_t panel, uint16_t x_start, uint16_t y_start, uint16_t x_end, uint16_t y_end) +{ + if (panel == NULL || x_start >= x_end || y_start >= y_end) { + return ESP_ERR_INVALID_ARG; + } + if (x_end > panel->cfg.h_res || y_end > panel->cfg.v_res) { + return ESP_ERR_INVALID_ARG; + } + + uint32_t panel_x_start = (uint32_t)x_start + panel->cfg.x_gap; + uint32_t panel_y_start = (uint32_t)y_start + panel->cfg.y_gap; + uint32_t panel_x_end = (uint32_t)x_end + panel->cfg.x_gap; + uint32_t panel_y_end = (uint32_t)y_end + panel->cfg.y_gap; + if (panel_x_end == 0 || panel_y_end == 0 || panel_x_end - 1 > UINT16_MAX || panel_y_end - 1 > UINT16_MAX) { + return ESP_ERR_INVALID_ARG; + } + + uint8_t x_data[4] = { + (uint8_t)(panel_x_start >> 8), + (uint8_t)(panel_x_start & 0xFF), + (uint8_t)((panel_x_end - 1) >> 8), + (uint8_t)((panel_x_end - 1) & 0xFF), + }; + uint8_t y_data[4] = { + (uint8_t)(panel_y_start >> 8), + (uint8_t)(panel_y_start & 0xFF), + (uint8_t)((panel_y_end - 1) >> 8), + (uint8_t)((panel_y_end - 1) & 0xFF), + }; + + esp_err_t ret = st7789p3_send_cmd(panel, 0x2A); + if (ret != ESP_OK) { + return ret; + } + ret = st7789p3_send_data(panel, x_data, sizeof(x_data)); + if (ret != ESP_OK) { + return ret; + } + + ret = st7789p3_send_cmd(panel, 0x2B); + if (ret != ESP_OK) { + return ret; + } + ret = st7789p3_send_data(panel, y_data, sizeof(y_data)); + if (ret != ESP_OK) { + return ret; + } + + return st7789p3_send_cmd(panel, 0x2C); +} + +esp_err_t st7789p3_draw_bitmap(st7789p3_handle_t panel, + uint16_t x_start, + uint16_t y_start, + uint16_t x_end, + uint16_t y_end, + const uint16_t *color_data) +{ + if (panel == NULL || color_data == NULL) { + return ESP_ERR_INVALID_ARG; + } + + esp_err_t ret = st7789p3_set_window(panel, x_start, y_start, x_end, y_end); + if (ret != ESP_OK) { + return ret; + } + + size_t pixel_count = (size_t)(x_end - x_start) * (size_t)(y_end - y_start); + return st7789p3_send_color_data(panel, color_data, pixel_count); +} + +esp_err_t st7789p3_fill_color(st7789p3_handle_t panel, uint16_t color) +{ + if (panel == NULL) { + return ESP_ERR_INVALID_ARG; + } + + static const size_t fill_pixels = 256; + uint16_t *fill_buffer = heap_caps_malloc(fill_pixels * sizeof(uint16_t), MALLOC_CAP_DMA | MALLOC_CAP_INTERNAL); + if (fill_buffer == NULL) { + return ESP_ERR_NO_MEM; + } + + uint16_t fill_color = color; + if (panel->cfg.swap_color_bytes) { + fill_color = (uint16_t)((color >> 8) | (color << 8)); + } + for (size_t i = 0; i < fill_pixels; i++) { + fill_buffer[i] = fill_color; + } + + esp_err_t ret = st7789p3_set_window(panel, 0, 0, panel->cfg.h_res, panel->cfg.v_res); + if (ret != ESP_OK) { + free(fill_buffer); + return ret; + } + + size_t total_pixels = (size_t)panel->cfg.h_res * (size_t)panel->cfg.v_res; + while (total_pixels > 0) { + size_t pixels_to_send = (total_pixels > fill_pixels) ? fill_pixels : total_pixels; + ret = st7789p3_send_data(panel, fill_buffer, pixels_to_send * sizeof(uint16_t)); + if (ret != ESP_OK) { + free(fill_buffer); + return ret; + } + total_pixels -= pixels_to_send; + } + + free(fill_buffer); + return ESP_OK; +} diff --git a/components/platform/src/platform_bootstrap.c b/components/platform/src/platform_bootstrap.c new file mode 100644 index 0000000..4421198 --- /dev/null +++ b/components/platform/src/platform_bootstrap.c @@ -0,0 +1,244 @@ +#include "platform.h" + +#include + +#include "driver/gpio.h" +#include "esp_heap_caps.h" +#include "esp_log.h" +#include "mbedtls/platform.h" +#include "nvs_flash.h" +#include "sdkconfig.h" + +static bool s_initialized; +static bool s_board_gpio_initialized; +static const char *TAG = "platform_bootstrap"; + +#ifndef CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT +#define CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT 1 +#endif + +#ifndef CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH +#define CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH 1 +#endif + +#ifndef CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH +#define CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH 1 +#endif + +#if CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT +#if CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH +#define KEY_PRINT_BOOST_LEVEL 1 +#else +#define KEY_PRINT_BOOST_LEVEL 0 +#endif +#endif + +#if CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH +#define BOOT_SCREEN_BACKLIGHT_ON_LEVEL 1 +#else +#define BOOT_SCREEN_BACKLIGHT_ON_LEVEL 0 +#endif + +static void *tls_calloc_prefer_psram(size_t n, size_t size) { + void *ptr = heap_caps_calloc(n, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT); + if (ptr == NULL) { + ptr = heap_caps_calloc(n, size, MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT); + } + return ptr; +} + +static void tls_free(void *ptr) { + heap_caps_free(ptr); +} + +static esp_err_t board_gpio_config_output(int gpio_num, int level, const char *name) { + if (gpio_num < 0) { + return ESP_OK; + } + + gpio_config_t cfg = { + .pin_bit_mask = 1ULL << gpio_num, + .mode = GPIO_MODE_OUTPUT, + .pull_up_en = GPIO_PULLUP_DISABLE, + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .intr_type = GPIO_INTR_DISABLE, + }; + esp_err_t err = gpio_config(&cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_config output failed: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + return err; + } + err = gpio_set_level(gpio_num, level); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_set_level failed: %s pin=%d level=%d err=%s", name, gpio_num, level, esp_err_to_name(err)); + return err; + } + return ESP_OK; +} + +static esp_err_t board_gpio_config_input(int gpio_num, bool pull_up, const char *name) { + if (gpio_num < 0) { + return ESP_OK; + } + + gpio_config_t cfg = { + .pin_bit_mask = 1ULL << gpio_num, + .mode = GPIO_MODE_INPUT, + .pull_up_en = pull_up ? GPIO_PULLUP_ENABLE : GPIO_PULLUP_DISABLE, + .pull_down_en = GPIO_PULLDOWN_DISABLE, + .intr_type = GPIO_INTR_DISABLE, + }; + esp_err_t err = gpio_config(&cfg); + if (err != ESP_OK) { + ESP_LOGE(TAG, "gpio_config input failed: %s pin=%d err=%s", name, gpio_num, esp_err_to_name(err)); + return err; + } + return ESP_OK; +} + +static esp_err_t platform_board_gpio_init(void) { + if (s_board_gpio_initialized) { + return ESP_OK; + } + + // Must be asserted early to keep the board powered. + esp_err_t err = board_gpio_config_output(CONFIG_TQ_POWER_HOLD_PIN, 1, "power_hold"); + if (err != ESP_OK) { + return err; + } + + // Default UI GPIO states. + err = board_gpio_config_output(CONFIG_TQ_LED_R_PIN, 0, "led_r"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_output(CONFIG_TQ_LED_G_PIN, 0, "led_g"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_output(CONFIG_TQ_SCREEN_CS_PIN, 1, "screen_cs"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_output(CONFIG_TQ_SCREEN_DC_PIN, 0, "screen_dc"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_output(CONFIG_TQ_SCREEN_BACKLIGHT_PIN, + BOOT_SCREEN_BACKLIGHT_ON_LEVEL, + "screen_backlight"); + if (err != ESP_OK) { + return err; + } + + // Key/power/sensor GPIO input defaults. + err = board_gpio_config_input(CONFIG_TQ_POWER_KEY_PIN, true, "power_key"); + if (err != ESP_OK) { + return err; + } +#if CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT + err = board_gpio_config_output(CONFIG_TQ_KEY_PRINT_PIN, KEY_PRINT_BOOST_LEVEL, "key_print_boost"); + if (err != ESP_OK) { + return err; + } +#else + err = board_gpio_config_input(CONFIG_TQ_KEY_PRINT_PIN, true, "key_print"); + if (err != ESP_OK) { + return err; + } +#endif + err = board_gpio_config_input(CONFIG_TQ_MIC_KEY_PIN, true, "mic_key"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_input(CONFIG_TQ_PRINT_PAPER_PIN, true, "print_paper"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_input(CONFIG_TQ_BATTERY_ADC_PIN, false, "battery_adc"); + if (err != ESP_OK) { + return err; + } + err = board_gpio_config_input(CONFIG_TQ_NTC_ADC_PIN, false, "ntc_adc"); + if (err != ESP_OK) { + return err; + } + + ESP_LOGI(TAG, + "board gpio mapped: hold=%d pwr_key=%d key_print=%d boost_mode=%d led_r=%d led_g=%d spi(mosi=%d,miso=%d,clk=%d) screen(dc=%d,cs=%d,bk=%d) i2c(sda=%d,scl=%d) i2s(mclk=%d,bclk=%d,ws=%d,di=%d,do=%d) pa=%d", + CONFIG_TQ_POWER_HOLD_PIN, + CONFIG_TQ_POWER_KEY_PIN, + CONFIG_TQ_KEY_PRINT_PIN, +#if CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT + 1, +#else + 0, +#endif + CONFIG_TQ_LED_R_PIN, + CONFIG_TQ_LED_G_PIN, + CONFIG_TQ_SPI_SHARED_MOSI_PIN, + CONFIG_TQ_PRINTER_MISO_PIN, + CONFIG_TQ_SPI_SHARED_CLK_PIN, + CONFIG_TQ_SCREEN_DC_PIN, + CONFIG_TQ_SCREEN_CS_PIN, + CONFIG_TQ_SCREEN_BACKLIGHT_PIN, + CONFIG_TQ_VOICE_I2C_SDA_PIN, + CONFIG_TQ_VOICE_I2C_SCL_PIN, + CONFIG_TQ_VOICE_I2S_MCLK_PIN, + CONFIG_TQ_VOICE_I2S_BCLK_PIN, + CONFIG_TQ_VOICE_I2S_WS_PIN, + CONFIG_TQ_VOICE_I2S_DIN_PIN, + CONFIG_TQ_VOICE_I2S_DOUT_PIN, + CONFIG_TQ_VOICE_CODEC_PA_PIN); + + s_board_gpio_initialized = true; + return ESP_OK; +} + +esp_err_t platform_bootstrap_init(void) { + if (s_initialized) { + return ESP_OK; + } + + ESP_ERROR_CHECK(platform_board_gpio_init()); + + esp_err_t err = nvs_flash_init(); + if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) { + ESP_ERROR_CHECK(nvs_flash_erase()); + err = nvs_flash_init(); + } + ESP_ERROR_CHECK(err); + +#if CONFIG_SPIRAM_USE_MALLOC + // Keep very small allocations on internal RAM, push larger generic mallocs to PSRAM. + heap_caps_malloc_extmem_enable(4096); + ESP_LOGI(TAG, "extmem malloc threshold set to 4096 bytes"); +#endif + +#if defined(MBEDTLS_PLATFORM_MEMORY) + int tls_rc = mbedtls_platform_set_calloc_free(tls_calloc_prefer_psram, tls_free); + if (tls_rc == 0) { + ESP_LOGI(TAG, "mbedtls calloc/free redirected to PSRAM-preferred allocator"); + } else { + ESP_LOGW(TAG, "mbedtls calloc/free redirect failed: rc=%d", tls_rc); + } +#endif + +#if CONFIG_TQ_SCREEN_ENABLE + err = platform_display_init(); + if (err != ESP_OK) { + ESP_LOGW(TAG, "st7789 init failed: %s", esp_err_to_name(err)); + } +#if CONFIG_TQ_SCREEN_TEST_PATTERN_ON_BOOT + else { + err = platform_display_show_test_pattern(); + if (err != ESP_OK) { + ESP_LOGW(TAG, "st7789 test pattern failed: %s", esp_err_to_name(err)); + } + } +#endif +#endif + + s_initialized = true; + return ESP_OK; +} diff --git a/components/platform/src/runtime_diagnostics.c b/components/platform/src/runtime_diagnostics.c new file mode 100644 index 0000000..1d8c844 --- /dev/null +++ b/components/platform/src/runtime_diagnostics.c @@ -0,0 +1,136 @@ +#include "platform.h" + +#include +#include + +#include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" + +static SemaphoreHandle_t s_lock; +static runtime_diag_snapshot_t s_snapshot; + +static const char *const s_counter_names[RUNTIME_DIAG_COUNTER_MAX] = { + "lifecycle_start_attempt", + "lifecycle_start_success", + "lifecycle_start_failed", + "lifecycle_start_retry", + "lifecycle_stop_attempt", + "lifecycle_stop_success", + "lifecycle_stop_failed", + "wifi_connect_success", + "wifi_connect_failed", + "wifi_connect_timeout", + "printer_job_submitted", + "printer_job_success", + "printer_job_failed", + "printer_job_canceled", + "image_generate_attempt", + "image_generate_success", + "image_generate_failed", + "image_generate_timeout", + "rest_responses_total", + "rest_errors_total", +}; + +static const char *const s_gauge_names[RUNTIME_DIAG_GAUGE_MAX] = { + "lifecycle_state", + "status_poll_pause_depth", + "printer_queue_depth", +}; + +static void runtime_diag_ensure_lock(void) { + if (s_lock == NULL) { + s_lock = xSemaphoreCreateMutex(); + } +} + +void runtime_diag_counter_add(runtime_diag_counter_t counter, uint32_t delta) { + if (counter < 0 || counter >= RUNTIME_DIAG_COUNTER_MAX || delta == 0) { + return; + } + + runtime_diag_ensure_lock(); + if (s_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(50)) != pdTRUE) { + return; + } + s_snapshot.counters[counter] += delta; + xSemaphoreGive(s_lock); +} + +void runtime_diag_set_gauge(runtime_diag_gauge_t gauge, int32_t value) { + if (gauge < 0 || gauge >= RUNTIME_DIAG_GAUGE_MAX) { + return; + } + + runtime_diag_ensure_lock(); + if (s_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(50)) != pdTRUE) { + return; + } + s_snapshot.gauges[gauge] = value; + xSemaphoreGive(s_lock); +} + +void runtime_diag_record_error(const char *source, esp_err_t code, const char *message) { + runtime_diag_ensure_lock(); + if (s_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(100)) != pdTRUE) { + return; + } + + s_snapshot.last_error_ms = esp_timer_get_time() / 1000; + s_snapshot.last_error_code = code; + strlcpy(s_snapshot.last_error_source, + source != NULL ? source : "unknown", + sizeof(s_snapshot.last_error_source)); + strlcpy(s_snapshot.last_error_message, + message != NULL ? message : "unknown", + sizeof(s_snapshot.last_error_message)); + + xSemaphoreGive(s_lock); +} + +void runtime_diag_get_snapshot(runtime_diag_snapshot_t *out_snapshot) { + if (out_snapshot == NULL) { + return; + } + + memset(out_snapshot, 0, sizeof(*out_snapshot)); + + runtime_diag_ensure_lock(); + if (s_lock == NULL) { + return; + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(100)) != pdTRUE) { + return; + } + + *out_snapshot = s_snapshot; + xSemaphoreGive(s_lock); +} + +const char *runtime_diag_counter_name(runtime_diag_counter_t counter) { + if (counter < 0 || counter >= RUNTIME_DIAG_COUNTER_MAX) { + return "unknown"; + } + return s_counter_names[counter]; +} + +const char *runtime_diag_gauge_name(runtime_diag_gauge_t gauge) { + if (gauge < 0 || gauge >= RUNTIME_DIAG_GAUGE_MAX) { + return "unknown"; + } + return s_gauge_names[gauge]; +} diff --git a/components/platform/src/runtime_policy.c b/components/platform/src/runtime_policy.c new file mode 100644 index 0000000..eeb6d30 --- /dev/null +++ b/components/platform/src/runtime_policy.c @@ -0,0 +1,319 @@ +#include "platform.h" + +#include + +#ifndef CONFIG_TQ_WIFI_CONNECT_TIMEOUT_MS +#define CONFIG_TQ_WIFI_CONNECT_TIMEOUT_MS 15000 +#endif + +#ifndef CONFIG_TQ_LIFECYCLE_START_RETRY_COUNT +#define CONFIG_TQ_LIFECYCLE_START_RETRY_COUNT 2 +#endif + +#ifndef CONFIG_TQ_LIFECYCLE_RETRY_BACKOFF_MS +#define CONFIG_TQ_LIFECYCLE_RETRY_BACKOFF_MS 800 +#endif + +#ifndef CONFIG_TQ_PRINTER_CONTROL_LOCK_TIMEOUT_MS +#define CONFIG_TQ_PRINTER_CONTROL_LOCK_TIMEOUT_MS 1000 +#endif + +#ifndef CONFIG_TQ_PRINTER_WORKER_QUEUE_WAIT_MS +#define CONFIG_TQ_PRINTER_WORKER_QUEUE_WAIT_MS 250 +#endif + +#ifndef CONFIG_TQ_PRINTER_QUEUE_RETRY_DELAY_MS +#define CONFIG_TQ_PRINTER_QUEUE_RETRY_DELAY_MS 20 +#endif + +#ifndef CONFIG_TQ_PRINTER_STATUS_POLL_INTERVAL_MS +#define CONFIG_TQ_PRINTER_STATUS_POLL_INTERVAL_MS 5000 +#endif + +#ifndef CONFIG_TQ_PRINTER_STOP_TIMEOUT_MS +#define CONFIG_TQ_PRINTER_STOP_TIMEOUT_MS 8000 +#endif + +#ifndef CONFIG_TQ_PRINTER_DEFAULT_BACKEND +#define CONFIG_TQ_PRINTER_DEFAULT_BACKEND 0 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_ENABLE +#define CONFIG_TQ_DIRECT_PRINTER_ENABLE 1 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_OPERATION_TIMEOUT_MS +#define CONFIG_TQ_DIRECT_PRINTER_OPERATION_TIMEOUT_MS 90000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_STROBE_ON_US +#define CONFIG_TQ_DIRECT_PRINTER_STROBE_ON_US 1000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_STROBE_INTERVAL_US +#define CONFIG_TQ_DIRECT_PRINTER_STROBE_INTERVAL_US 200 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_MOTOR_STEP_US +#define CONFIG_TQ_DIRECT_PRINTER_MOTOR_STEP_US 2000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_MOTOR_REVERSE +#define CONFIG_TQ_DIRECT_PRINTER_MOTOR_REVERSE 0 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_STEPS_PER_LINE +#define CONFIG_TQ_DIRECT_PRINTER_STEPS_PER_LINE 2 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_GAP_STEPS +#define CONFIG_TQ_DIRECT_PRINTER_GAP_STEPS 96 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_TEMP_MIN_C +#define CONFIG_TQ_DIRECT_PRINTER_TEMP_MIN_C 15 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_TEMP_MAX_C +#define CONFIG_TQ_DIRECT_PRINTER_TEMP_MAX_C 55 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_BATTERY_MIN_PERCENT +#define CONFIG_TQ_DIRECT_PRINTER_BATTERY_MIN_PERCENT 5 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_PAPER_PRESENT_LEVEL +#define CONFIG_TQ_DIRECT_PRINTER_PAPER_PRESENT_LEVEL 0 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_BATTERY_EMPTY_MV +#define CONFIG_TQ_DIRECT_PRINTER_BATTERY_EMPTY_MV 3300 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_BATTERY_FULL_MV +#define CONFIG_TQ_DIRECT_PRINTER_BATTERY_FULL_MV 4200 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_BATTERY_DIVIDER_RATIO_X1000 +#define CONFIG_TQ_DIRECT_PRINTER_BATTERY_DIVIDER_RATIO_X1000 2000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_NTC_PULLUP_OHMS +#define CONFIG_TQ_DIRECT_PRINTER_NTC_PULLUP_OHMS 10000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_NTC_R25_OHMS +#define CONFIG_TQ_DIRECT_PRINTER_NTC_R25_OHMS 10000 +#endif + +#ifndef CONFIG_TQ_DIRECT_PRINTER_NTC_BETA +#define CONFIG_TQ_DIRECT_PRINTER_NTC_BETA 3950 +#endif + +#ifndef CONFIG_TQ_REST_PRINTER_CONNECT_TIMEOUT_MS +#define CONFIG_TQ_REST_PRINTER_CONNECT_TIMEOUT_MS 15000 +#endif + +#ifndef CONFIG_TQ_REST_LABEL_TIMEOUT_MS +#define CONFIG_TQ_REST_LABEL_TIMEOUT_MS 5000 +#endif + +#ifndef CONFIG_TQ_REST_OTA_STEP_TIMEOUT_MS +#define CONFIG_TQ_REST_OTA_STEP_TIMEOUT_MS 5000 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_TIMEOUT_MS +#define CONFIG_TQ_Z_IMAGE_TIMEOUT_MS 45000 +#endif + +#ifndef CONFIG_TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS +#define CONFIG_TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS 15000 +#endif + +static uint32_t clamp_u32(uint32_t value, uint32_t min_value, uint32_t max_value) { + if (value < min_value) { + return min_value; + } + if (value > max_value) { + return max_value; + } + return value; +} + +static uint16_t clamp_u16(uint16_t value, uint16_t min_value, uint16_t max_value) { + if (value < min_value) { + return min_value; + } + if (value > max_value) { + return max_value; + } + return value; +} + +static uint8_t clamp_u8(uint8_t value, uint8_t min_value, uint8_t max_value) { + if (value < min_value) { + return min_value; + } + if (value > max_value) { + return max_value; + } + return value; +} + +uint32_t runtime_policy_wifi_connect_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_WIFI_CONNECT_TIMEOUT_MS, 3000, 60000); +} + +uint32_t runtime_policy_lifecycle_start_retry_count(void) { + return clamp_u32(CONFIG_TQ_LIFECYCLE_START_RETRY_COUNT, 0, 5); +} + +uint32_t runtime_policy_lifecycle_retry_backoff_ms(uint32_t attempt) { + uint32_t base = clamp_u32(CONFIG_TQ_LIFECYCLE_RETRY_BACKOFF_MS, 100, 10000); + if (attempt > 8) { + attempt = 8; + } + uint32_t factor = (1u << attempt); + return clamp_u32(base * factor, 100, 30000); +} + +bool runtime_policy_is_retryable_error(esp_err_t err) { + return err == ESP_ERR_TIMEOUT || err == ESP_FAIL || err == ESP_ERR_NO_MEM; +} + +uint32_t runtime_policy_printer_control_lock_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_PRINTER_CONTROL_LOCK_TIMEOUT_MS, 100, 5000); +} + +uint32_t runtime_policy_printer_worker_queue_wait_ms(void) { + return clamp_u32(CONFIG_TQ_PRINTER_WORKER_QUEUE_WAIT_MS, 50, 2000); +} + +uint32_t runtime_policy_printer_queue_retry_delay_ms(void) { + return clamp_u32(CONFIG_TQ_PRINTER_QUEUE_RETRY_DELAY_MS, 5, 500); +} + +uint32_t runtime_policy_printer_status_poll_interval_ms(void) { + return clamp_u32(CONFIG_TQ_PRINTER_STATUS_POLL_INTERVAL_MS, 1000, 30000); +} + +uint32_t runtime_policy_printer_stop_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_PRINTER_STOP_TIMEOUT_MS, 1000, 30000); +} + +uint8_t runtime_policy_printer_default_backend(void) { + return (uint8_t)clamp_u32(CONFIG_TQ_PRINTER_DEFAULT_BACKEND, 0, 1); +} + +bool runtime_policy_direct_printer_enabled(void) { + return CONFIG_TQ_DIRECT_PRINTER_ENABLE != 0; +} + +uint32_t runtime_policy_direct_printer_operation_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_DIRECT_PRINTER_OPERATION_TIMEOUT_MS, 1000, 300000); +} + +uint16_t runtime_policy_direct_printer_strobe_on_us(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_STROBE_ON_US, 100, 10000); +} + +uint16_t runtime_policy_direct_printer_strobe_interval_us(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_STROBE_INTERVAL_US, 0, 10000); +} + +uint16_t runtime_policy_direct_printer_motor_step_us(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_MOTOR_STEP_US, 100, 20000); +} + +bool runtime_policy_direct_printer_motor_reverse(void) { + return CONFIG_TQ_DIRECT_PRINTER_MOTOR_REVERSE != 0; +} + +uint8_t runtime_policy_direct_printer_steps_per_line(void) { + return clamp_u8((uint8_t)CONFIG_TQ_DIRECT_PRINTER_STEPS_PER_LINE, 1, 8); +} + +uint16_t runtime_policy_direct_printer_gap_steps(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_GAP_STEPS, 1, 2000); +} + +float runtime_policy_direct_printer_temp_min_c(void) { + return (float)clamp_u32((uint32_t)CONFIG_TQ_DIRECT_PRINTER_TEMP_MIN_C, 0, 120); +} + +float runtime_policy_direct_printer_temp_max_c(void) { + return (float)clamp_u32((uint32_t)CONFIG_TQ_DIRECT_PRINTER_TEMP_MAX_C, 1, 150); +} + +uint8_t runtime_policy_direct_printer_battery_min_percent(void) { + return clamp_u8((uint8_t)CONFIG_TQ_DIRECT_PRINTER_BATTERY_MIN_PERCENT, 0, 100); +} + +uint8_t runtime_policy_direct_printer_paper_present_level(void) { + return clamp_u8((uint8_t)CONFIG_TQ_DIRECT_PRINTER_PAPER_PRESENT_LEVEL, 0, 1); +} + +uint16_t runtime_policy_direct_printer_battery_empty_mv(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_BATTERY_EMPTY_MV, 2500, 5000); +} + +uint16_t runtime_policy_direct_printer_battery_full_mv(void) { + uint16_t empty_mv = runtime_policy_direct_printer_battery_empty_mv(); + uint16_t full_mv = clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_BATTERY_FULL_MV, 2600, 6000); + if (full_mv <= empty_mv) { + full_mv = (uint16_t)(empty_mv + 100); + } + return full_mv; +} + +uint16_t runtime_policy_direct_printer_battery_divider_ratio_x1000(void) { + return clamp_u16((uint16_t)CONFIG_TQ_DIRECT_PRINTER_BATTERY_DIVIDER_RATIO_X1000, 1000, 10000); +} + +uint32_t runtime_policy_direct_printer_ntc_pullup_ohms(void) { + return clamp_u32(CONFIG_TQ_DIRECT_PRINTER_NTC_PULLUP_OHMS, 1000, 200000); +} + +uint32_t runtime_policy_direct_printer_ntc_r25_ohms(void) { + return clamp_u32(CONFIG_TQ_DIRECT_PRINTER_NTC_R25_OHMS, 1000, 200000); +} + +uint32_t runtime_policy_direct_printer_ntc_beta(void) { + return clamp_u32(CONFIG_TQ_DIRECT_PRINTER_NTC_BETA, 1000, 10000); +} + +uint32_t runtime_policy_rest_printer_connect_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_REST_PRINTER_CONNECT_TIMEOUT_MS, 1000, 60000); +} + +uint32_t runtime_policy_rest_label_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_REST_LABEL_TIMEOUT_MS, 500, 30000); +} + +uint32_t runtime_policy_rest_ota_timeout_ms(void) { + return clamp_u32(CONFIG_TQ_REST_OTA_STEP_TIMEOUT_MS, 500, 60000); +} + +uint32_t runtime_policy_image_generation_timeout_default_ms(void) { + return clamp_u32(CONFIG_TQ_Z_IMAGE_TIMEOUT_MS, 5000, 180000); +} + +uint32_t runtime_policy_image_generation_timeout_min_ms(void) { + return 5000; +} + +uint32_t runtime_policy_image_generation_timeout_max_ms(void) { + return 180000; +} + +uint32_t runtime_policy_image_download_timeout_default_ms(void) { + return clamp_u32(CONFIG_TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS, 2000, 120000); +} + +uint32_t runtime_policy_image_download_timeout_min_ms(void) { + return 2000; +} + +uint32_t runtime_policy_image_download_timeout_max_ms(void) { + return 120000; +} diff --git a/components/platform/src/voice_audio.c b/components/platform/src/voice_audio.c new file mode 100644 index 0000000..9b6a8fa --- /dev/null +++ b/components/platform/src/voice_audio.c @@ -0,0 +1,496 @@ +#include "platform.h" + +#include +#include + +#include "audio_codec_if.h" +#include "driver/i2s_std.h" +#include "esp_check.h" +#include "esp_codec_dev.h" +#include "esp_codec_dev_defaults.h" +#include "esp_idf_version.h" +#include "esp_log.h" +#include "es8311_codec.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" + +#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0) && !defined(CONFIG_CODEC_I2C_BACKWARD_COMPATIBLE) +#include "driver/i2c_master.h" +#define VOICE_USE_IDF_I2C_MASTER +#else +#include "driver/i2c.h" +#endif + +static const char *TAG = "voice_audio"; +static const uint32_t VOICE_CODEC_I2C_PROBE_TIMEOUT_MS = 50; + +#define ES8311_CODEC_ALT_ADDR ((uint8_t)(ES8311_CODEC_DEFAULT_ADDR + 0x02)) + +#ifdef CONFIG_TQ_VOICE_CODEC_PA_PIN_REVERSED +#define VOICE_CODEC_PA_REVERSED true +#else +#define VOICE_CODEC_PA_REVERSED false +#endif + +static SemaphoreHandle_t s_lock; + +#ifdef VOICE_USE_IDF_I2C_MASTER +static i2c_master_bus_handle_t s_i2c_bus; +#endif + +static i2s_chan_handle_t s_i2s_tx; +static i2s_chan_handle_t s_i2s_rx; + +static const audio_codec_ctrl_if_t *s_codec_ctrl_if; +static const audio_codec_gpio_if_t *s_codec_gpio_if; +static const audio_codec_data_if_t *s_codec_data_if; +static const audio_codec_if_t *s_codec_if; +static esp_codec_dev_handle_t s_codec_dev; + +static bool s_initialized; +static bool s_opened; +static uint32_t s_sample_rate; +static uint8_t s_channels; +static uint8_t s_bits_per_sample; +static bool s_i2s_need_enable_before_open; + +static void fill_err(char *err, size_t err_len, const char *msg) { + if (err != NULL && err_len > 0) { + snprintf(err, err_len, "%s", msg != NULL ? msg : "unknown error"); + } +} + +static bool voice_audio_i2c_probe_addr(uint8_t addr_8bit) { +#ifdef VOICE_USE_IDF_I2C_MASTER + if (s_i2c_bus == NULL || addr_8bit == 0) { + return false; + } + uint16_t addr_7bit = (uint16_t)(addr_8bit >> 1); + return i2c_master_probe(s_i2c_bus, addr_7bit, (int)VOICE_CODEC_I2C_PROBE_TIMEOUT_MS) == ESP_OK; +#else + if (addr_8bit == 0) { + return false; + } + + i2c_cmd_handle_t cmd = i2c_cmd_link_create(); + if (cmd == NULL) { + return false; + } + + i2c_master_start(cmd); + i2c_master_write_byte(cmd, addr_8bit, true); + i2c_master_stop(cmd); + + esp_err_t err = i2c_master_cmd_begin(CONFIG_TQ_VOICE_I2C_PORT, + cmd, + pdMS_TO_TICKS(VOICE_CODEC_I2C_PROBE_TIMEOUT_MS)); + i2c_cmd_link_delete(cmd); + return err == ESP_OK; +#endif +} + +static uint8_t voice_audio_resolve_codec_addr(uint8_t preferred_addr) { + uint8_t candidates[3] = {preferred_addr, ES8311_CODEC_DEFAULT_ADDR, ES8311_CODEC_ALT_ADDR}; + for (size_t i = 0; i < 3; ++i) { + uint8_t addr = candidates[i]; + bool duplicate = false; + for (size_t j = 0; j < i; ++j) { + if (candidates[j] == addr) { + duplicate = true; + break; + } + } + if (duplicate) { + continue; + } + + if (voice_audio_i2c_probe_addr(addr)) { + return addr; + } + } + + ESP_LOGW(TAG, + "ES8311 not found on I2C(port=%d,sda=%d,scl=%d), tried addrs:0x%02x/0x%02x/0x%02x", + CONFIG_TQ_VOICE_I2C_PORT, + CONFIG_TQ_VOICE_I2C_SDA_PIN, + CONFIG_TQ_VOICE_I2C_SCL_PIN, + (unsigned)preferred_addr, + (unsigned)ES8311_CODEC_DEFAULT_ADDR, + (unsigned)ES8311_CODEC_ALT_ADDR); + return preferred_addr; +} + +static esp_err_t voice_audio_init_i2c(void) { +#ifdef VOICE_USE_IDF_I2C_MASTER + if (s_i2c_bus != NULL) { + return ESP_OK; + } + + i2c_master_bus_config_t bus_cfg = { + .clk_source = I2C_CLK_SRC_DEFAULT, + .i2c_port = CONFIG_TQ_VOICE_I2C_PORT, + .sda_io_num = CONFIG_TQ_VOICE_I2C_SDA_PIN, + .scl_io_num = CONFIG_TQ_VOICE_I2C_SCL_PIN, + .glitch_ignore_cnt = 7, + .flags.enable_internal_pullup = true, + }; + + esp_err_t err = i2c_new_master_bus(&bus_cfg, &s_i2c_bus); + if (err == ESP_OK) { + ESP_LOGI(TAG, + "voice i2c ready: port=%d sda=%d scl=%d", + CONFIG_TQ_VOICE_I2C_PORT, + CONFIG_TQ_VOICE_I2C_SDA_PIN, + CONFIG_TQ_VOICE_I2C_SCL_PIN); + } + return err; +#else + i2c_config_t i2c_cfg = { + .mode = I2C_MODE_MASTER, + .sda_io_num = CONFIG_TQ_VOICE_I2C_SDA_PIN, + .scl_io_num = CONFIG_TQ_VOICE_I2C_SCL_PIN, + .sda_pullup_en = GPIO_PULLUP_ENABLE, + .scl_pullup_en = GPIO_PULLUP_ENABLE, + .master.clk_speed = 100000, + }; + + ESP_RETURN_ON_ERROR(i2c_param_config(CONFIG_TQ_VOICE_I2C_PORT, &i2c_cfg), TAG, "i2c_param_config failed"); + esp_err_t err = i2c_driver_install(CONFIG_TQ_VOICE_I2C_PORT, i2c_cfg.mode, 0, 0, 0); + if (err == ESP_OK) { + ESP_LOGI(TAG, + "voice i2c ready: port=%d sda=%d scl=%d", + CONFIG_TQ_VOICE_I2C_PORT, + CONFIG_TQ_VOICE_I2C_SDA_PIN, + CONFIG_TQ_VOICE_I2C_SCL_PIN); + } + return err; +#endif +} + +static esp_err_t voice_audio_init_i2s(uint32_t sample_rate) { + if (s_i2s_tx != NULL && s_i2s_rx != NULL) { + return ESP_OK; + } + + i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG((i2s_port_t)CONFIG_TQ_VOICE_I2S_PORT, + I2S_ROLE_MASTER); + chan_cfg.dma_desc_num = 6; + chan_cfg.dma_frame_num = 240; + + ESP_RETURN_ON_ERROR(i2s_new_channel(&chan_cfg, &s_i2s_tx, &s_i2s_rx), TAG, "i2s_new_channel failed"); + + i2s_std_config_t std_cfg = { + .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(sample_rate), + .slot_cfg = I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(I2S_DATA_BIT_WIDTH_16BIT, I2S_SLOT_MODE_MONO), + .gpio_cfg = { + .mclk = CONFIG_TQ_VOICE_I2S_MCLK_PIN, + .bclk = CONFIG_TQ_VOICE_I2S_BCLK_PIN, + .ws = CONFIG_TQ_VOICE_I2S_WS_PIN, + .dout = CONFIG_TQ_VOICE_I2S_DOUT_PIN, + .din = CONFIG_TQ_VOICE_I2S_DIN_PIN, + .invert_flags = { + .mclk_inv = false, + .bclk_inv = false, + .ws_inv = false, + }, + }, + }; + + esp_err_t err = i2s_channel_init_std_mode(s_i2s_tx, &std_cfg); + if (err != ESP_OK) { + return err; + } + + err = i2s_channel_init_std_mode(s_i2s_rx, &std_cfg); + if (err != ESP_OK) { + return err; + } + + ESP_RETURN_ON_ERROR(i2s_channel_enable(s_i2s_tx), TAG, "i2s tx enable failed"); + ESP_RETURN_ON_ERROR(i2s_channel_enable(s_i2s_rx), TAG, "i2s rx enable failed"); + return ESP_OK; +} + +static esp_err_t voice_audio_build_codec_dev(void) { + if (s_codec_dev != NULL) { + return ESP_OK; + } + + uint8_t codec_addr = voice_audio_resolve_codec_addr((uint8_t)CONFIG_TQ_VOICE_CODEC_ADDR); + if (codec_addr != (uint8_t)CONFIG_TQ_VOICE_CODEC_ADDR) { + ESP_LOGW(TAG, + "override ES8311 I2C addr 0x%02x -> 0x%02x", + (unsigned)CONFIG_TQ_VOICE_CODEC_ADDR, + (unsigned)codec_addr); + } + ESP_LOGI(TAG, + "voice codec cfg: i2c_port=%d addr=0x%02x i2s_port=%d mclk=%d bclk=%d ws=%d dout=%d din=%d", + CONFIG_TQ_VOICE_I2C_PORT, + (unsigned)codec_addr, + CONFIG_TQ_VOICE_I2S_PORT, + CONFIG_TQ_VOICE_I2S_MCLK_PIN, + CONFIG_TQ_VOICE_I2S_BCLK_PIN, + CONFIG_TQ_VOICE_I2S_WS_PIN, + CONFIG_TQ_VOICE_I2S_DOUT_PIN, + CONFIG_TQ_VOICE_I2S_DIN_PIN); + + audio_codec_i2c_cfg_t i2c_cfg = { + .port = (uint8_t)CONFIG_TQ_VOICE_I2C_PORT, + .addr = codec_addr, +#ifdef VOICE_USE_IDF_I2C_MASTER + .bus_handle = s_i2c_bus, +#endif + }; + + s_codec_ctrl_if = audio_codec_new_i2c_ctrl(&i2c_cfg); + if (s_codec_ctrl_if == NULL) { + return ESP_ERR_NO_MEM; + } + + audio_codec_i2s_cfg_t i2s_cfg = { + .port = (uint8_t)CONFIG_TQ_VOICE_I2S_PORT, + .rx_handle = s_i2s_rx, + .tx_handle = s_i2s_tx, + }; + + s_codec_data_if = audio_codec_new_i2s_data(&i2s_cfg); + if (s_codec_data_if == NULL) { + return ESP_ERR_NO_MEM; + } + + s_codec_gpio_if = audio_codec_new_gpio(); + if (s_codec_gpio_if == NULL) { + return ESP_ERR_NO_MEM; + } + + es8311_codec_cfg_t codec_cfg = { + .ctrl_if = s_codec_ctrl_if, + .gpio_if = s_codec_gpio_if, + .codec_mode = ESP_CODEC_DEV_WORK_MODE_BOTH, + .pa_pin = CONFIG_TQ_VOICE_CODEC_PA_PIN, + .pa_reverted = VOICE_CODEC_PA_REVERSED, + .master_mode = false, + .use_mclk = (CONFIG_TQ_VOICE_I2S_MCLK_PIN >= 0), + .digital_mic = false, + .invert_mclk = false, + .invert_sclk = false, + }; + + s_codec_if = es8311_codec_new(&codec_cfg); + if (s_codec_if == NULL) { + ESP_LOGE(TAG, "es8311_codec_new failed, check I2C wiring/pull-up/address"); + return ESP_FAIL; + } + + esp_codec_dev_cfg_t dev_cfg = { + .dev_type = ESP_CODEC_DEV_TYPE_IN_OUT, + .codec_if = s_codec_if, + .data_if = s_codec_data_if, + }; + + s_codec_dev = esp_codec_dev_new(&dev_cfg); + if (s_codec_dev == NULL) { + return ESP_ERR_NO_MEM; + } + + return ESP_OK; +} + +static esp_err_t voice_audio_prepare(const voice_audio_open_config_t *cfg) { + ESP_RETURN_ON_ERROR(voice_audio_init_i2c(), TAG, "i2c init failed"); + ESP_RETURN_ON_ERROR(voice_audio_init_i2s(cfg->sample_rate), TAG, "i2s init failed"); + ESP_RETURN_ON_ERROR(voice_audio_build_codec_dev(), TAG, "codec dev init failed"); + return ESP_OK; +} + +static esp_err_t voice_audio_reenable_i2s_if_needed(void) { + if (!s_i2s_need_enable_before_open) { + return ESP_OK; + } + if (s_i2s_tx == NULL || s_i2s_rx == NULL) { + s_i2s_need_enable_before_open = false; + return ESP_OK; + } + + esp_err_t tx_rc = i2s_channel_enable(s_i2s_tx); + if (tx_rc != ESP_OK && tx_rc != ESP_ERR_INVALID_STATE) { + return tx_rc; + } + + esp_err_t rx_rc = i2s_channel_enable(s_i2s_rx); + if (rx_rc != ESP_OK && rx_rc != ESP_ERR_INVALID_STATE) { + return rx_rc; + } + + s_i2s_need_enable_before_open = false; + return ESP_OK; +} + +esp_err_t voice_audio_open(const voice_audio_open_config_t *cfg, char *err, size_t err_len) { + if (cfg == NULL || cfg->sample_rate == 0 || cfg->channels == 0 || cfg->bits_per_sample != 16) { + fill_err(err, err_len, "invalid voice audio config"); + return ESP_ERR_INVALID_ARG; + } + + if (s_lock == NULL) { + s_lock = xSemaphoreCreateMutex(); + if (s_lock == NULL) { + fill_err(err, err_len, "create mutex failed"); + return ESP_ERR_NO_MEM; + } + } + + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + fill_err(err, err_len, "voice audio lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (s_opened) { + xSemaphoreGive(s_lock); + return ESP_OK; + } + + esp_err_t init_err = voice_audio_prepare(cfg); + if (init_err != ESP_OK) { + if (init_err == ESP_FAIL) { + fill_err(err, err_len, "es8311 init failed, check i2c wiring/address"); + } else { + fill_err(err, err_len, "voice audio peripheral init failed"); + } + xSemaphoreGive(s_lock); + return init_err; + } + + if (s_initialized && (s_sample_rate != cfg->sample_rate || + s_channels != cfg->channels || + s_bits_per_sample != cfg->bits_per_sample)) { + fill_err(err, err_len, "voice audio format changed after init"); + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + esp_err_t i2s_rc = voice_audio_reenable_i2s_if_needed(); + if (i2s_rc != ESP_OK) { + fill_err(err, err_len, "i2s re-enable failed"); + xSemaphoreGive(s_lock); + return i2s_rc; + } + + esp_codec_dev_sample_info_t fs = { + .sample_rate = cfg->sample_rate, + .channel = cfg->channels, + .bits_per_sample = cfg->bits_per_sample, + }; + + int rc = esp_codec_dev_open(s_codec_dev, &fs); + if (rc != ESP_CODEC_DEV_OK) { + fill_err(err, err_len, "esp_codec_dev_open failed"); + xSemaphoreGive(s_lock); + return ESP_FAIL; + } + + (void)esp_codec_dev_set_out_vol(s_codec_dev, cfg->output_volume); + (void)esp_codec_dev_set_in_gain(s_codec_dev, cfg->input_gain_db); + (void)esp_codec_dev_set_out_mute(s_codec_dev, false); + (void)esp_codec_dev_set_in_mute(s_codec_dev, false); + + s_sample_rate = cfg->sample_rate; + s_channels = cfg->channels; + s_bits_per_sample = cfg->bits_per_sample; + s_initialized = true; + s_opened = true; + + ESP_LOGI(TAG, + "voice audio opened: sr=%u ch=%u bits=%u", + (unsigned)s_sample_rate, + (unsigned)s_channels, + (unsigned)s_bits_per_sample); + + xSemaphoreGive(s_lock); + return ESP_OK; +} + +void voice_audio_close(void) { + if (s_lock == NULL) { + return; + } + if (xSemaphoreTake(s_lock, pdMS_TO_TICKS(1000)) != pdTRUE) { + return; + } + + if (s_opened) { + (void)esp_codec_dev_set_in_mute(s_codec_dev, true); + (void)esp_codec_dev_set_out_mute(s_codec_dev, true); + (void)esp_codec_dev_close(s_codec_dev); + s_opened = false; + s_i2s_need_enable_before_open = true; + } + + xSemaphoreGive(s_lock); +} + +bool voice_audio_is_open(void) { + return s_opened; +} + +esp_err_t voice_audio_read_pcm(int16_t *pcm, + size_t samples, + uint32_t timeout_ms, + char *err, + size_t err_len) { + if (pcm == NULL || samples == 0) { + fill_err(err, err_len, "invalid read args"); + return ESP_ERR_INVALID_ARG; + } + + if (s_lock == NULL || xSemaphoreTake(s_lock, pdMS_TO_TICKS(timeout_ms)) != pdTRUE) { + fill_err(err, err_len, "voice read lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_opened) { + fill_err(err, err_len, "voice audio not opened"); + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + int rc = esp_codec_dev_read(s_codec_dev, pcm, (int)(samples * sizeof(int16_t))); + xSemaphoreGive(s_lock); + if (rc != ESP_CODEC_DEV_OK) { + fill_err(err, err_len, "codec read failed"); + return ESP_FAIL; + } + + return ESP_OK; +} + +esp_err_t voice_audio_write_pcm(const int16_t *pcm, + size_t samples, + uint32_t timeout_ms, + char *err, + size_t err_len) { + if (pcm == NULL || samples == 0) { + fill_err(err, err_len, "invalid write args"); + return ESP_ERR_INVALID_ARG; + } + + if (s_lock == NULL || xSemaphoreTake(s_lock, pdMS_TO_TICKS(timeout_ms)) != pdTRUE) { + fill_err(err, err_len, "voice write lock timeout"); + return ESP_ERR_TIMEOUT; + } + + if (!s_opened) { + fill_err(err, err_len, "voice audio not opened"); + xSemaphoreGive(s_lock); + return ESP_ERR_INVALID_STATE; + } + + int rc = esp_codec_dev_write(s_codec_dev, (void *)pcm, (int)(samples * sizeof(int16_t))); + xSemaphoreGive(s_lock); + if (rc != ESP_CODEC_DEV_OK) { + fill_err(err, err_len, "codec write failed"); + return ESP_FAIL; + } + + return ESP_OK; +} diff --git a/components/platform/src/wifi_manager.c b/components/platform/src/wifi_manager.c new file mode 100644 index 0000000..24f986a --- /dev/null +++ b/components/platform/src/wifi_manager.c @@ -0,0 +1,325 @@ +#include "platform.h" + +#include +#include + +#include "esp_event.h" +#include "esp_log.h" +#include "esp_netif.h" +#include "esp_wifi.h" +#include "esp_wifi_default.h" +#include "freertos/FreeRTOS.h" +#include "freertos/event_groups.h" + +#define WIFI_CONNECTED_BIT BIT0 +#define WIFI_FAIL_BIT BIT1 + +static const char *TAG = "wifi_manager"; + +static EventGroupHandle_t s_wifi_event_group; +static int s_retry_num; +static bool s_ready; +static bool s_started; +static esp_netif_t *s_sta_netif; +static esp_event_handler_instance_t s_wifi_event_inst; +static esp_event_handler_instance_t s_ip_event_inst; + +static void wifi_manager_apply_sta_throughput_profile(void) { + const uint8_t protocol = WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N; + esp_err_t proto_rc = esp_wifi_set_protocol(WIFI_IF_STA, protocol); + if (proto_rc != ESP_OK) { + ESP_LOGW(TAG, "failed to set 11bgn protocol mask, rc=0x%x", (unsigned)proto_rc); + } else { + ESP_LOGI(TAG, "Wi-Fi protocol mask set to 11b/11g/11n"); + } + + esp_err_t bw_rc = esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT40); + if (bw_rc == ESP_OK) { + ESP_LOGI(TAG, "Wi-Fi bandwidth set to HT40"); + return; + } + + ESP_LOGW(TAG, "failed to set HT40, fallback to HT20, rc=0x%x", (unsigned)bw_rc); + bw_rc = esp_wifi_set_bandwidth(WIFI_IF_STA, WIFI_BW_HT20); + if (bw_rc != ESP_OK) { + ESP_LOGW(TAG, "failed to set HT20 fallback, rc=0x%x", (unsigned)bw_rc); + } else { + ESP_LOGI(TAG, "Wi-Fi bandwidth set to HT20"); + } +} + +static void wifi_event_handler(void *arg, + esp_event_base_t event_base, + int32_t event_id, + void *event_data) { + (void)arg; + (void)event_data; + + if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START) { + if (!s_started) { + return; + } + (void)esp_wifi_connect(); + return; + } + + if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) { + s_ready = false; + if (!s_started) { + return; + } + if (s_retry_num < CONFIG_TQ_WIFI_MAXIMUM_RETRY) { + (void)esp_wifi_connect(); + s_retry_num++; + ESP_LOGW(TAG, "retry to connect to the AP (%d/%d)", s_retry_num, CONFIG_TQ_WIFI_MAXIMUM_RETRY); + } else if (s_wifi_event_group != NULL) { + xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT); + } + return; + } + + if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) { + if (!s_started) { + return; + } + ip_event_got_ip_t *event = (ip_event_got_ip_t *)event_data; + ESP_LOGI(TAG, "got ip:" IPSTR, IP2STR(&event->ip_info.ip)); + s_retry_num = 0; + s_ready = true; + if (s_wifi_event_group != NULL) { + xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT); + } + return; + } +} + +static esp_err_t start_sta_mode(void) { + wifi_config_t wifi_config = {0}; + if (strlen(CONFIG_TQ_WIFI_SSID) == 0) { + ESP_LOGE(TAG, "CONFIG_TQ_WIFI_SSID is empty; STA-only mode requires valid SSID"); + return ESP_ERR_INVALID_STATE; + } + + strlcpy((char *)wifi_config.sta.ssid, CONFIG_TQ_WIFI_SSID, sizeof(wifi_config.sta.ssid)); + strlcpy((char *)wifi_config.sta.password, CONFIG_TQ_WIFI_PASSWORD, sizeof(wifi_config.sta.password)); + wifi_config.sta.threshold.authmode = WIFI_AUTH_WPA2_PSK; + wifi_config.sta.pmf_cfg.capable = true; + wifi_config.sta.pmf_cfg.required = false; + + esp_err_t rc = esp_wifi_set_mode(WIFI_MODE_STA); + if (rc != ESP_OK) { + return rc; + } + rc = esp_wifi_set_config(WIFI_IF_STA, &wifi_config); + if (rc != ESP_OK) { + return rc; + } + rc = esp_wifi_start(); + if (rc != ESP_OK && rc != ESP_ERR_INVALID_STATE) { + return rc; + } + + ESP_LOGI(TAG, "wifi_init_sta finished"); + + EventBits_t bits = xEventGroupWaitBits(s_wifi_event_group, + WIFI_CONNECTED_BIT | WIFI_FAIL_BIT, + pdFALSE, + pdFALSE, + pdMS_TO_TICKS(runtime_policy_wifi_connect_timeout_ms())); + + if (bits & WIFI_CONNECTED_BIT) { + ESP_LOGI(TAG, "connected to AP SSID:%s", CONFIG_TQ_WIFI_SSID); + wifi_manager_apply_sta_throughput_profile(); + esp_err_t ps_rc = esp_wifi_set_ps(WIFI_PS_NONE); + if (ps_rc == ESP_OK) { + ESP_LOGI(TAG, "Wi-Fi power save disabled (WIFI_PS_NONE)"); + } else { + ESP_LOGW(TAG, "failed to set WIFI_PS_NONE, rc=0x%x", (unsigned)ps_rc); + } + s_ready = true; + return ESP_OK; + } + + if (bits & WIFI_FAIL_BIT) { + ESP_LOGW(TAG, "Failed to connect to SSID:%s", CONFIG_TQ_WIFI_SSID); + return ESP_FAIL; + } + + ESP_LOGW(TAG, "Wi-Fi connect timeout"); + return ESP_ERR_TIMEOUT; +} + +esp_err_t wifi_manager_start(void) { + if (s_started) { + return s_ready ? ESP_OK : ESP_ERR_INVALID_STATE; + } + + s_retry_num = 0; + s_ready = false; + + if (s_wifi_event_group == NULL) { + s_wifi_event_group = xEventGroupCreate(); + if (s_wifi_event_group == NULL) { + return ESP_ERR_NO_MEM; + } + } + xEventGroupClearBits(s_wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT); + + esp_err_t err = esp_netif_init(); + if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) { + runtime_diag_record_error("wifi_start", err, "esp_netif_init failed"); + return err; + } + + err = esp_event_loop_create_default(); + if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) { + runtime_diag_record_error("wifi_start", err, "event loop init failed"); + return err; + } + + if (s_sta_netif == NULL) { + s_sta_netif = esp_netif_create_default_wifi_sta(); + if (s_sta_netif == NULL) { + runtime_diag_record_error("wifi_start", ESP_ERR_NO_MEM, "create sta netif failed"); + return ESP_ERR_NO_MEM; + } + } + + wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT(); + err = esp_wifi_init(&cfg); + if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) { + runtime_diag_record_error("wifi_start", err, "esp_wifi_init failed"); + return err; + } + + if (s_wifi_event_inst == NULL) { + err = esp_event_handler_instance_register(WIFI_EVENT, + ESP_EVENT_ANY_ID, + &wifi_event_handler, + NULL, + &s_wifi_event_inst); + if (err != ESP_OK) { + runtime_diag_record_error("wifi_start", err, "register WIFI event failed"); + return err; + } + } + + if (s_ip_event_inst == NULL) { + err = esp_event_handler_instance_register(IP_EVENT, + IP_EVENT_STA_GOT_IP, + &wifi_event_handler, + NULL, + &s_ip_event_inst); + if (err != ESP_OK) { + runtime_diag_record_error("wifi_start", err, "register IP event failed"); + return err; + } + } + + s_started = true; + err = start_sta_mode(); + if (err == ESP_OK) { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_WIFI_CONNECT_SUCCESS, 1); + } else { + if (err == ESP_ERR_TIMEOUT) { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_WIFI_CONNECT_TIMEOUT, 1); + } else { + runtime_diag_counter_add(RUNTIME_DIAG_COUNTER_WIFI_CONNECT_FAILED, 1); + } + runtime_diag_record_error("wifi_connect", err, "STA connect failed"); + (void)wifi_manager_stop(); + } + return err; +} + +esp_err_t wifi_manager_stop(void) { + if (!s_started) { + return ESP_OK; + } + + esp_err_t first_err = ESP_OK; + + s_ready = false; + s_retry_num = 0; + + if (s_wifi_event_inst != NULL) { + esp_err_t err = esp_event_handler_instance_unregister(WIFI_EVENT, + ESP_EVENT_ANY_ID, + s_wifi_event_inst); + if (err != ESP_OK && first_err == ESP_OK) { + first_err = err; + } + s_wifi_event_inst = NULL; + } + + if (s_ip_event_inst != NULL) { + esp_err_t err = esp_event_handler_instance_unregister(IP_EVENT, + IP_EVENT_STA_GOT_IP, + s_ip_event_inst); + if (err != ESP_OK && first_err == ESP_OK) { + first_err = err; + } + s_ip_event_inst = NULL; + } + + esp_err_t err = esp_wifi_disconnect(); + if (err != ESP_OK && err != ESP_ERR_WIFI_NOT_STARTED && err != ESP_ERR_WIFI_CONN) { + if (first_err == ESP_OK) { + first_err = err; + } + } + + err = esp_wifi_stop(); + if (err != ESP_OK && err != ESP_ERR_WIFI_NOT_INIT && err != ESP_ERR_WIFI_NOT_STARTED) { + if (first_err == ESP_OK) { + first_err = err; + } + } + + err = esp_wifi_deinit(); + if (err != ESP_OK && err != ESP_ERR_WIFI_NOT_INIT) { + if (first_err == ESP_OK) { + first_err = err; + } + } + + if (s_sta_netif != NULL) { + esp_netif_destroy_default_wifi(s_sta_netif); + s_sta_netif = NULL; + } + + if (s_wifi_event_group != NULL) { + vEventGroupDelete(s_wifi_event_group); + s_wifi_event_group = NULL; + } + + s_started = false; + + if (first_err != ESP_OK) { + runtime_diag_record_error("wifi_stop", first_err, "wifi stop failed"); + } + + return first_err; +} + +bool wifi_manager_is_ready(void) { + return s_ready; +} + +void wifi_manager_get_ip(char *buf, size_t buf_len) { + if (buf == NULL || buf_len == 0) { + return; + } + + buf[0] = '\0'; + + esp_netif_ip_info_t ip_info; + memset(&ip_info, 0, sizeof(ip_info)); + + if (s_sta_netif != NULL && esp_netif_get_ip_info(s_sta_netif, &ip_info) == ESP_OK) { + snprintf(buf, buf_len, IPSTR, IP2STR(&ip_info.ip)); + return; + } + + strlcpy(buf, "0.0.0.0", buf_len); +} diff --git a/dependencies.lock b/dependencies.lock new file mode 100644 index 0000000..1944d13 --- /dev/null +++ b/dependencies.lock @@ -0,0 +1,76 @@ +dependencies: + espressif/esp_audio_codec: + component_hash: af4663830bc73eca58febcc34a976d003465e78ed57458aa00a14b231e392ca1 + dependencies: + - name: idf + require: private + version: '>=4.4' + source: + registry_url: https://components.espressif.com/ + type: service + version: 2.4.1 + espressif/esp_codec_dev: + component_hash: 0d9e9bc288156eb55f79338d312e1ebf8c9dfbd5e7d13ef0f20ccb031b4e15cf + dependencies: + - name: idf + require: private + version: '>=4.0' + source: + registry_url: https://components.espressif.com/ + type: service + version: 1.5.4 + espressif/esp_websocket_client: + component_hash: c5a067a9fddea370c478017e66fac302f4b79c3d4027e9bdd42a019786cceb92 + dependencies: + - name: idf + require: private + version: '>=5.0' + source: + registry_url: https://components.espressif.com/ + type: service + version: 1.6.1 + espressif/libpng: + component_hash: 8c426d10dc2bf187aafd84ef42834e1a44835ed08a293d78683eb7811d8f8c25 + dependencies: + - name: idf + require: private + version: '>=5.0' + - name: espressif/zlib + registry_url: https://components.espressif.com + require: private + version: ^1.2.13 + source: + registry_url: https://components.espressif.com/ + type: service + version: 1.6.55 + espressif/zlib: + component_hash: 64ea2fd6754c5a05951f1ddb312ac835cd782e68cb5bd9dfcd1c3a107c8fbfbc + dependencies: + - name: idf + require: private + version: '>=4.4' + source: + registry_url: https://components.espressif.com + type: service + version: 1.3.2 + idf: + source: + type: idf + version: 5.5.2 + lvgl/lvgl: + component_hash: d7c1ac037ae6e85d94897f807d6e7ba0946a83e720074fc95a4f6241da9f9f53 + dependencies: [] + source: + registry_url: https://components.espressif.com/ + type: service + version: 8.4.0 +direct_dependencies: +- espressif/esp_audio_codec +- espressif/esp_codec_dev +- espressif/esp_websocket_client +- espressif/libpng +- idf +- lvgl/lvgl +manifest_hash: d32a494b7c86c11954a7b0354da8967836fc6789173852455b8c0611e1898436 +target: esp32s3 +version: 2.0.0 diff --git a/dependency_whitelist.md b/dependency_whitelist.md new file mode 100644 index 0000000..a77af50 --- /dev/null +++ b/dependency_whitelist.md @@ -0,0 +1,13 @@ +# Dependency Whitelist + +Use this file only when a same-level or lateral dependency is unavoidable. + +Entry format: +- requester: `/` +- target: `/` +- reason: short technical justification +- owner: person/team +- expiry: YYYY-MM-DD (must be reviewed before expiry) + +Current entries: +- none diff --git a/docs/gpio-map.md b/docs/gpio-map.md new file mode 100644 index 0000000..d36bbe3 --- /dev/null +++ b/docs/gpio-map.md @@ -0,0 +1,65 @@ +# ESP32-S3 GPIO Mapping + +本文件记录当前板级 GPIO 分配,来源于硬件对接表(2026-02-26)。 + +## GPIO Table + +| Board Pin | GPIO | Signal | Direction | Notes | +| --- | --- | --- | --- | --- | +| 1 | GND | GND | - | Ground | +| 2 | 3V3 | 3V3 | - | 3.3V Power | +| 3 | EN/RST | EN | Input | Chip enable/reset | +| 4 | IO4 | PRINT_STB5_6 | Output | Printer strobe 5/6 | +| 5 | IO5 | PRINT_STB3_4 | Output | Printer strobe 3/4 | +| 6 | IO6 | ES8311_I2C_SDA | Bidirectional | Voice codec I2C SDA | +| 7 | IO7 | ES8311_I2C_SCL | Output | Voice codec I2C SCL | +| 8 | IO15 | BATTERY_ADC | Input | Battery voltage ADC detect | +| 9 | IO16 | PRINT_STB1_2 | Output | Printer strobe 1/2 | +| 10 | IO17 | PRINT_PAPER | Input | Paper detect | +| 11 | IO18 | NTC_ADC | Input | NTC ADC | +| 12 | IO8 | PRINT_OUTA_P | Output | Printer OUTA+ | +| 13 | IO19 | PRINT_OUTA_N | Output | Printer OUTA- | +| 14 | IO20 | ES8311_PA | Output | PA control | +| 15 | IO3 | PRINT_OUTB_P | Output | Printer OUTB+ | +| 16 | IO46 | PRINT_OUTB_N | Output | Printer OUTB- | +| 17 | IO9 | SPI_SHARED_MOSI | Output | Printer/Screen shared MOSI | +| 18 | IO10 | PRINTER_MISO | Input | Printer MISO | +| 19 | IO11 | SPI_SHARED_CLK | Output | Printer/Screen shared CLK | +| 20 | IO12 | SCREEN_DC | Output | ST7789 DC | +| 21 | IO13 | SCREEN_CS1 | Output | ST7789 CS | +| 22 | IO14 | MIC_KEY | Input | Mic key (can ADC-mux 2 keys if needed) | +| 23 | IO21 | LED_G | Output | Green LED | +| 24 | IO47 | POWER_KEY | Input | Hold low for 2s to request power-off logic | +| 25 | IO48 | SCREEN_BACKLIGHT | Output | High level turns backlight on | +| 26 | IO45 | PRINT_LAT | Output | Printer LAT | +| 27 | IO0 | KEY_PRINT / BOOST_CTRL | Input/Output | Print confirm key or 7.2V boost control | +| 28 | IO35 | N/A | - | Not available | +| 29 | IO36 | N/A | - | Not available | +| 30 | IO37 | N/A | - | Not available | +| 31 | IO38 | I2S_MCLK | Output | Voice I2S MCLK | +| 32 | IO39 | I2S_BCLK | Output | Voice I2S BCLK | +| 33 | IO40 | I2S_DI | Input | Voice I2S data in | +| 34 | IO41 | I2S_WS | Output | Voice I2S WS | +| 35 | IO42 | I2S_DO | Output | Voice I2S data out | +| 36 | TXD0 | UART0_TX | Output | Serial log/program | +| 37 | RXD0 | UART0_RX | Input | Serial log/program | +| 38 | IO2 | LED_R | Output | Red LED | +| 39 | IO1 | POWER_HOLD | Output | Must drive high at boot to keep board powered | +| 40 | GND | GND | - | Ground | +| 41 | GND | GND | - | Ground | + +## Firmware Mapping Notes + +- `main/Kconfig.projbuild` contains board pin configs prefixed with `TQ_*`. +- `components/platform/src/platform_bootstrap.c` initializes critical GPIO on startup: + - `POWER_HOLD` asserted high early. + - `SCREEN_DC/SCREEN_CS/SCREEN_BACKLIGHT` default states. + - `KEY_PRINT` defaults to boost-enable output mode (`CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT=y`). + - key/sensor inputs (`POWER_KEY`, `MIC_KEY`, `PRINT_PAPER`, ADC inputs) default directions. +- `components/platform/src/display_st7789.c` provides ST7789 driver integration: + - SPI bus (`MOSI=IO9`, `CLK=IO11`) + `esp_lcd_new_panel_st7789`. + - Optional boot test pattern via `CONFIG_TQ_SCREEN_TEST_PATTERN_ON_BOOT`. +- Voice codec and I2S pin defaults are aligned to this table: + - I2C: `SDA=6`, `SCL=7` + - I2S: `MCLK=38`, `BCLK=39`, `WS=41`, `DIN=40`, `DOUT=42` + - PA: `IO20` diff --git a/docs/websocket.md b/docs/websocket.md new file mode 100644 index 0000000..c1b01d4 --- /dev/null +++ b/docs/websocket.md @@ -0,0 +1,1164 @@ +本文介绍基于 WebSocket 协议的实时多模态交互 API。WebSocket协议延迟低、资源占用少,是首选接入方案。 + +WebSocket是一种支持全双工通信的网络协议。客户端和服务器通过一次握手建立持久连接,双方可以互相主动推送数据,因此在实时性和效率方面具有显著优势。 + +对于常用编程语言,有许多现成的WebSocket库和示例可供参考,例如: + +- Go:`gorilla/websocket` + +- PHP:`Ratchet` + +- Node.js:`ws` + + +建议您先了解WebSocket的基本原理和技术细节,再参照本文进行开发。 + +**说明** + +对于RTOS或某些旧版Linux系统,建立安全Websocket 通信所依赖的 TLS 隧道,需要做如下配置: + +- TLS 版本要求 TLS1.2 或以上 + +- 开启 SNI(SERVER NAME INDICATION) + +- 配置 CA 证书([GlobalSign Root CA - R3](https://secure.globalsign.net/cacert/Root-R3.crt))(也可至GlobalSign官网下载) + + +## **前提条件** + +已开通服务并[获取API Key](https://help.aliyun.com/zh/model-studio/get-api-key)。请[配置API Key到环境变量](https://help.aliyun.com/zh/model-studio/configure-api-key-through-environment-variables),而非硬编码在代码中,防范因代码泄露导致的安全风险。 + +**说明** + +对于客户端调用的场景,在客户端处理API Key有安全风险,建议从服务端用API Key获取临时鉴权Token,再把Token下发给客户端使用。具体方法请参考:[生成临时 API Key](https://help.aliyun.com/zh/model-studio/generate-temporary-api-key)。 + +## **调用时序图** + +**\[关键流程\]** 服务端返回`Started`消息表示会话创建成功,但客户端**禁止**立即发送音频。客户端必须等待并接收到`DialogStateChanged`事件且`state`为`Listening`后,方可开始发送音频流。 + +![image](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8963248471/p958632.png) + +## **服务地址** + +``` +wss://dashscope.aliyuncs.com/api-ws/v1/inference +``` + +## **鉴权** + +需要在发起初始的WebSocket握手(HTTP Upgrade)请求时,把API Key放在HTTP Header里(需要将your\_api\_key替换为真实的API Key): + +``` +"Authorization": "Bearer your_api_key" +``` + +## **语音交互** + +多模态交互应用开启了**语音交互**后,支持语音识别和语音合成。 + +语音识别支持的模型包括:[Gummy实时语音识别](https://help.aliyun.com/zh/model-studio/real-time-speech-recognition-and-translation-api-reference/)(Gummy),[Paraformer实时语音识别](https://help.aliyun.com/zh/model-studio/paraformer-real-time-speech-recognition-api-reference/)(Paraformer),[FUN-ASR实时语音识别](https://help.aliyun.com/zh/model-studio/fun-asr-real-time-speech-recognition-api-reference/)(FunASR),[千问3-ASR-Flash-Realtime](https://help.aliyun.com/zh/model-studio/qwen-real-time-speech-recognition)(qwen3-asr-flash-realtime),多模态交互轻量版语音识别(AppSpecificASR-Realtime)。 + +语音合成支持的模型包括:[语音合成CosyVoice-v2大模型](https://help.aliyun.com/zh/model-studio/cosyvoice-large-model-for-speech-synthesis/)(cosyvoice-v2),[语音合成CosyVoice-v3-plus大模型](https://help.aliyun.com/zh/model-studio/text-to-speech)(cosyvoice-v3-plus),[语音合成CosyVoice-v3-Flash大模型](https://help.aliyun.com/zh/model-studio/text-to-speech)(cosyvoice-v3-flash),[Sambert语音合成](https://help.aliyun.com/zh/model-studio/sambert-speech-synthesis/)(sambert),[千问3-TTS](https://help.aliyun.com/zh/model-studio/qwen-tts-realtime)(qwen3-tts),多模态交互轻量版语音合成(AppSpecificTTS)。 + +语音合成支持的音色,可以在控制台上选择了模型后,点击右侧语音交互体验区域的右上角查看音色列表。 + +官方音色也可以参考官方文档:cosyvoice-v2 / cosyvoice-v3-plus / cosyvoice-v3-flash 支持的官方音色参考[音色列表](https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list),qwen3-tts 支持的官方音色参考[支持的音色](https://help.aliyun.com/zh/model-studio/qwen-tts-realtime#422789c49bqqx),sambert支持的音色参考[模型列表](https://help.aliyun.com/zh/model-studio/sambert-java-sdk#74cedcb97el0b)(去掉开头的"sambert-"和末尾的"-v1"后就是voice的取值)。 + +使用复刻音色时,确认复刻音色状态为“OK”后才能使用。查询方法参考[查询指定音色](https://help.aliyun.com/zh/model-studio/cosyvoice-clone-api#34490e5a2by7z)。 + +## **消息类型** + +### **二进制消息(Binary Message)** + +当前二进制消息仅包含音频数据。 + +#### **上传音频** + +上传音频时,将原始音频直接转为二进制流即可,无需额外处理。 + +上传的语音识别音频需满足:16bit(采样位深)、单声道、有符号、little-endian PCM编码,采样率参考[Start](#5b2363d40585y)消息的参数parameters.upstream.sample\_rate的取值说明。 + +如果希望减少网络流量和带宽占用,用户可以把PCM音频编码为Opus格式,同时设置上传音频格式为raw-opus。 + +上传音频时,根据[Start](#5b2363d40585y)消息中`upstream.mode`设置不同,采取的措施也不同: + +- mode为 `tap2talk` 或 `duplex`:客户端需持续上传音频,服务端自动检测语音活动。建议每100ms上传一次数据,间隔太长或太短会对延时和处理效率造成负面影响。 + + - 音频上传速率计算公式:`数据每次上传的字节数 = 采样率 * 采样位深/8 * 时间间隔(ms)/ 1000` + + - 以16kHz采样率、16bit位深、100ms间隔为例,每次应上传 `16000 * (16/8) * 100 / 1000 = 3200` 字节的PCM数据。 + +- mode为 `push2talk`:客户端无需持续上传音频,但需通过[SendSpeech](#cec23c1556u8x)和[StopSpeech](#d11933e7b5jz0)通知服务端音频识别的开始和结束。发送[SendSpeech](#cec23c1556u8x)后需立即上传音频,否则会增加处理时间。 + + +#### **下发音频** + +服务端将大模型回复发送至TTS生成语音然后下发给客户端: + +- 下发音频为16bit单声道,采样率和编码由[Start](#5b2363d40585y)消息参数定义。 + +- 下发速度取决于TTS服务性能,通常快于播放速度。 + +- 音频下发前发送[RespondingStarted](#0693e9d4a5f91)事件;结束后发送[RespondingEnded](#402cbee340r1m)事件。 + +- 客户端需在播放完成后上报[LocalRespondingEnded](#f4b1a6bf22ymq),通知服务端播放结束。 + + +### **文本消息(Text Message)** + +文本消息是JSON格式字符串,按传递方向分为两类: + +- **输入消息(Input Message)**:客户端发送给服务端的指令(directive),表示客户端希望服务端执行特定动作。 + +- **输出消息(Output Message)**:服务端发送给客户端的事件(event),表示服务端动作执行结果或进展。 + + +文本消息标记交互流程的关键节点,控制流程并传输关键信息。通过[时序图](#6d25d6f8ddbtd)可了解不同消息的交互时序。 + +文本消息包含两部分:`header`和`payload`。 + +- `payload`:内容随[消息类型](#408ddb268eyt7)变化。 + +- `header`:内容固定,包含以下参数: + + | **参数** | **类型** | **是否必选** | **说明** | + | --- | --- | --- | --- | + | task\_id | string | 是 | 本次连接唯一标识,用于在工程链路上跟踪任务执行。由客户端生成,格式建议为36位uuid字符串,格式示例:"f894c16f-f20e-4c1d-837e-89e0fbc63a43" | + | streaming | string | 是 | 输入输出类型,对于多模态交互必须为 "duplex" ,表示流式输入,流式输出 | + | action | string | 是 | 模型输入消息类型: - run-task: 任务的第一个输入消息 - finish-task: 任务的最后一个输入消息 - continue-task: 任务中其他输入消息 | + + +## **连接保活策略** + +百炼平台规定,如果在**任意连续的60秒内**服务端没有向客户端发送任何消息,则认为调用发生错误,WebSocket连接将被服务端主动断开并返回`ResponseTimeout`错误。 + +若客户端需在无交互时保持连接,应定期发送心跳消息(HeartBeat)。服务端会回应心跳,确保连接活跃,避免超时关闭。 + +移动端和C++ SDK已内置心跳保活逻辑,用户无需手动发送。 + +## **文本消息类型** + +### **开始会话** + +#### **Start - Input Message** + +请求开始会话消息。服务收到Start消息后,向客户端发送**Started**消息。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| task\_group | | string | 是 | 任务组名称,固定为"aigc",请直接复制使用 | +| task | | string | 是 | 任务名称,固定为"multimodal-generation",请直接复制使用 | +| function | | string | 是 | 调用功能,固定为"generation",请直接复制使用 | +| model | | string | 是 | 阿里云百炼模型名称,固定为"multimodal-dialog",请直接复制使用 | +| input | directive | string | 是 | 指令名称:Start | +| input | workspace\_id | string | 是 | 客户在阿里云百炼业务空间ID([Workspace ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id#732535cfc959h)),可在**多模态交互开发套件控制**台,点击左下角业务空间名称,“业务空间详情”中查看,目前仅支持主账号默认工作空间。 | +| input | app\_id | string | 是 | 客户创建的应用ID([APP ID](https://help.aliyun.com/zh/model-studio/obtain-the-app-id-and-workspace-id#2612f896detsz)),可在**多模态交互开发套件**控制台的“我的应用”页面查看 | +| input | dialog\_id | string | 否 | 对话ID,默认不填时是开启新会话,服务端会自动生成并在事件中下发,格式示例:"12345678-1234-1234-1234-1234567890ab",共36个字符。当希望继续之前的对话时,把当时服务端下发的dialog\_id在这里传入 | +| parameters | upstream | object | 是 | 参数说明参考下方 [parameters.upstream的参数说明](#c70ad23b46rng)表格 | +| parameters | downstream | object | 否 | 参数说明参考下方 [parameters.downstream的参数说明](#18bc9ff97bxur)表格 | +| parameters | client\_info | object | 是 | 参数说明参考下方 [parameters.client\_info的参数说明](#51228f3bc17yk)表格 | +| parameters | biz\_params | object | 否 | 参数说明参考下方 [parameters.biz\_params的参数说明](#eb89a03bfdk00)表格 | + +**parameters.upstream**的参数说明如下**:** + +| **一级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | +| type | string | 是 | 上行类型: AudioOnly 仅语音通话 | +| mode | string | 否 | 客户端使用的模式,默认**tap2talk。** 可选项: - push2talk: 客户端控制模式。 - tap2talk: 点击模式。 - duplex: 双工模式。 三种模式的对比可以参考下方的[客户端使用的三种模式对比](#5e82453407pum)表格。 | +| audio\_format | string | 否 | 音频格式,支持pcm,raw-opus,默认为pcm | +| sample\_rate | int | 否 | 语音识别的采样率,支持范围: - 8000 - 16000 - 24000 - 48000 默认为16000 | +| vocabulary\_id | string | 否 | 热词id,设置该参数时会覆盖管控台热词配置。当管控台提供的热词不能满足客户需求时,可以考虑用Open API程序化管理热词,参见[热词API文档](https://next.api.aliyun.com/document/MultimodalDialog/2025-09-03/Vocabulary) | + +**parameters.downstream**的参数说明如下: + +| **一级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | +| voice | string | 否 | 合成语音的音色,支持范围取决于用户在管控台选择的语音合成模型 | +| sample\_rate | int | 否 | 合成语音的采样率,支持范围: - 8000 - 16000 - 24000 - 48000 默认为24000。 千问-TTS、千问3-TTS模型仅支持24000。 | +| audio\_format | string | 否 | 音频格式,支持pcm,opus,mp3,raw-opus,默认为pcm。 千问-TTS模型仅支持pcm。 注意:opus 和 raw-opus的区别是opus格式的每一包数据都有额外ogg封装([RFC 7845](https://www.rfc-editor.org/rfc/rfc7845.html)) | +| frame\_size | int | 否 | 合成音频的帧大小,取值范围: - 10 - 20 - 40 - 60 - 100 - 120 默认值为60,单位ms 只在合成音频格式为opus或raw-opus时生效 | +| volume | int | 否 | 合成音频的音量,取值范围0-100,默认50 | +| speech\_rate | int | 否 | 合成音频的语速,取值范围50-200,表示默认语速的50%-200%,默认100 | +| pitch\_rate | int | 否 | 合成音频的声调,取值范围50-200,默认100 | +| bit\_rate | int | 否 | 合成音频的比特率,取值范围:6~510kbps,默认值为32,单位kbps,只在合成音频格式为opus或raw-opus时生效 | +| intermediate\_text | string | 否 | 控制返回给用户哪些中间文本: - transcript:返回用户语音识别结果 - dialog:返回对话系统回答中间结果 可以设置多种,以逗号分隔,默认为transcript | +| transmit\_rate\_limit | int | 否 | 下发音频发送速率限制,单位:字节每秒 | +| incremental\_response | boolean | 否 | 是否增量返回大模型结果,true为增量,false为全量。默认为false,全量下发 | + +**parameters.client\_info**的参数说明如下: + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| user\_id | | string | 是 | 终端用户ID,客户根据自己业务规则生成,用来针对不同终端用户实现定制化功能。最大长度36个字符。 | +| device.uuid | uuid | string | 否 | 客户端全局唯一的ID,需要用户自己生成并传入SDK,最大长度40个字符。一个终端用户可以有多个设备,那么每一个设备的uuid都不同,但user\_id相同。 | +| network | ip | string | 否 | 调用方公网IP | +| location | latitude | string | 否 | 调用方纬度信息,在需要客户端精确位置的业务场景提交 | +| location | longitude | string | 否 | 调用方经度信息,在需要客户端精确位置的业务场景提交 | +| location | city\_name | string | 否 | 调用方所在城市,指明客户端粗略位置 | + +**parameters.biz\_params**的参数说明如下: + +| **一级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | +| user\_defined\_params | json object | 否 | 需要透传给agent的参数,各类agent传递的参数参考[调用官方Agent](https://help.aliyun.com/zh/model-studio/official-agent)文档说明 | +| user\_prompt\_params | json object | 否 | 用于设置用户自定义prompt变量,由用户自定义设置json中的key和value。管控台上配置自定义prompt变量的方法参考[应用配置-提示词](https://help.aliyun.com/zh/model-studio/multimodal-app-configuration#74a8b82973u0r) | +| user\_query\_params | json object | 否 | 用于设置用户自定义对话变量,由用户自定义设置json中的key和value。管控台上配置自定义对话变量的方法参考[应用配置-对话变量](https://help.aliyun.com/zh/model-studio/multimodal-app-configuration#62d90ef075ve1) | + +##### **客户端使用的三种模式对比:** + +| **对比项** | **push2talk** | **tap2talk** | **duplex** | +| --- | --- | --- | --- | +| 类型 | 客户端控制模式 | 点击模式 | 双工模式 | +| 音频上传方式 | 按需 | 持续 Listening状态超过20秒不上传音频即报错 | 持续 任何状态超过20秒不上传音频都报错 | +| VAD检测方 | 客户端 | 服务端 | 服务端 | +| 打断方式 | [RequestToSpeak](#8f987c58ddg2i)消息打断 | [RequestToSpeak](#8f987c58ddg2i)消息打断 | 语音打断 | +| 使用场景 | 由用户控制开始/结束客户端语音发送和识别,适用于按键说话,松开停止说话的场景。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。但不支持用户语音打断大模型输出,只能发送RequestToSpeak打断消息。 | 客户端需持续上传音频,服务端自动检测语音活动的场景。用户随时可以说话打断大模型输出。 | + +示例如下: + +``` +{ + "header": { + "action":"run-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "task_group":"aigc", + "task":"multimodal-generation", // 任务类型:多模态生成 + "function":"generation", + "model":"multimodal-dialog", // 模型名称:多模态对话(注意与task不同) + "input":{ + "directive": "Start", + "workspace_id": "llm-***********", + "app_id": "****************" + }, + "parameters":{ + "upstream":{ + "type": "AudioOnly", + "mode": "duplex" + }, + "downstream":{ + "voice": "longxiaochun_v2", + "sample_rate": 24000 + }, + "client_info":{ + "user_id": "bin********207", + "device":{ + "uuid": "432k*********k449" + }, + "network":{ + "ip": "203.0.113.10" + }, + "location":{ + "city_name": "北京市" + } + }, + "biz_params":{ + "user_defined_params": { + "agent_id_xxxxx": { + "name": "value" + } + }, + "user_prompt_params": { + "name": "value" + }, + "user_query_params": { + "name": "value" + } + } + } + } +} +``` + +#### **Started - Output Message** + +**说明** + +SDK接收到**Started**之后,先不可以向服务发送音频,应等待**DialogStateChanged**消息,确认切换到Listening状态之后才发送音频。 + +| **一级参数** | **二级参数** | **类型** | **说明** | +| --- | --- | --- | --- | +| output | event | string | 事件名称:Started | +| | dialog\_id | string | 对话ID | + +示例如下: + +Started返回消息样例 + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "Started", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **结束会话** + +#### **Stop - Input Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:Stop | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +Stop请求样例 + +``` +{ + "header": { + "action":"finish-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "Stop", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **Stopped - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:Stopped | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "Stopped", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **服务端下发状态切换事件** + +#### **DialogStateChanged - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:DialogStateChanged | +| | state | string | 是 | AI交互状态,取值范围:Listening,Thinking, Responding 注意:其中状态Listening 只是表示SDK可以发语音给服务端,不代表客户端是否开麦 | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "DialogStateChanged", + "state": "Listening", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **请求上传语音** + +#### **RequestToSpeak - Input Message** + +当前状态不是Listening,而用户又想说话时,先提交此事件打断大模型的回答,等待服务端应答。 + +具体触发此事件的用户行为根据交互类型有所不同,比如用户按下按钮、语音打断(依赖双工模块)等。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:RequestToSpeak | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "RequestToSpeak", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **RequestAccepted - Output Message 请求被准许** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:RequestAccepted | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "RequestAccepted", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **上传语音指令** + +#### **SendSpeech - Input Message** + +当Start消息指定模式为push2talk,需要客户端告知服务端用户何时开始说话。在Listening状态下,当用户按下按键时应上报SendSpeech消息,通知服务端即将开始上传语音,语音数据应紧接着此事件之后发送。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:SendSpeech | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "SendSpeech", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **StopSpeech - Input Message** + +当Start消息指定模式为push2talk的时候,用户说完话松开按键时,客户端必须使用StopSpeech消息通知服务端结束语音指令输入。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:StopSpeech | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "StopSpeech", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **CancelSpeech - Input Message** + +当Start消息指定模式为push2talk或tap2talk的时候,在语音输入过程中,用户可以使用CancelSpeech消息结束语音输入。服务会结束识别,回到空闲状态。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:CancelSpeech | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "CancelSpeech", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **语音识别开始/结束** + +#### **SpeechStarted - Output Message** + +当服务端检测到asr语音起点时下发此事件。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:SpeechStarted | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "SpeechStarted", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **SpeechEnded - Output Message** + +当服务端检测到asr语音尾点时下发此事件,如果客户端还在上传音频,则收到此事件后应停止上传音频。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:SpeechEnded | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "SpeechEnded", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **指定应答内容** + +#### **RequestToRespond - Input Message** + +在Listening状态时,通知服务端与用户主动交互,服务端会根据type字段把在text字段中上传的文本直接转换为语音下发,或调用大模型,返回的结果再转换为语音下发。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:RequestToRespond | +| input | dialog\_id | string | 是 | 对话ID | +| input | type | string | 是 | 服务应该采取的交互类型,目前支持两种: - transcript:表示直接把文本转语音 - prompt:表示把文本发送给大模型让其进行回答 | +| input | text | string | 是 | 要处理的文本,非null。 - 调用部分agent时,text可以是""空字符串,服务端只需要使用parameters中的images或者biz\_params参数即可处理。具体参考[调用官方Agent](https://help.aliyun.com/zh/model-studio/official-agent)。 | +| parameters | images | list\[\] | 否 | 需要分析的图片信息 | +| parameters | biz\_params | object | 否 | 参数说明参考下方 [parameters.biz\_params的参数说明](#b5975e73ab3s0)表格 | + +**parameters.biz\_params**的参数说明如下: + +| **一级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | +| videos | list\[\] | 否 | 用来控制进入和退出视频通话。 示例如下: payload.biz\_params.videos.action为connect,表示进入视频模式。 payload.biz\_params.videos.action为exit,表示退出视频模式。 | +| 其他参数 | | 否 | 与[Start](#5b2363d40585y)消息中`parameters.biz_params`相同,传递对话系统自定义参数。RequestToRespond的`biz_params`参数只在本次请求中生效。 | + +**说明** + +除了videos参数外,`parameters.biz_params`与[Start](#5b2363d40585y)消息中的`parameters.biz_params`相同,传递对话系统自定义参数。RequestToRespond的`biz_params`参数只在本次请求中生效。 + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "RequestToRespond", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb", + "type": "prompt", + "text": "你好,你有什么想聊的呢" + }, + "parameters":{ + "images":[{ + "type": "base64", + "value": "aGVsbG8gd29ybGQ=" + }], + "biz_params":{ + "user_defined_params":{}, + "videos": [ + { + "action": "connect/exit", + "type": "voicechat_video_channel" + } + ] + } + } + } +} +``` + +### **AI语音应答状态** + +#### **RespondingStarted - Output Message** + +AI语音应答开始,sdk要准备接收服务端下发的语音数据 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:RespondingStarted | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "RespondingStarted", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **RespondingEnded - Output Message** + +AI语音应答结束 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:RespondingEnded | +| | dialog\_id | string | 是 | 对话ID | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "RespondingEnded", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### 客户端**播放事件** + +#### **LocalRespondingStarted - Input Message** + +客户端开始播放服务端下发的音频 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:LocalRespondingStarted | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "LocalRespondingStarted", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **LocalRespondingEnded - Input Message** + +客户端播放服务端下发的音频完成,服务端根据此消息判断端侧语音播放结束,结束当前问答,重新切换到Listening状态。 + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:LocalRespondingEnded | +| | dialog\_id | string | 否 | 对话ID | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "LocalRespondingEnded", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **文本下发事件** + +#### **SpeechContent - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:SpeechContent | +| | dialog\_id | string | 是 | 对话ID | +| | text | string | 是 | 用户语音识别出的文本,流式返回,每次返回从识别开始到当前的完整识别结果。例如,您会先收到`"text": "你好"`,接着收到`"text": "你好世界"`。 | +| | finished | bool | 是 | 输出是否结束 | + +示例如下: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "SpeechContent", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb", + "text": "一二三", + "finished": false + } + } +} +``` + +#### **RespondingContent - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:RespondingContent | +| | dialog\_id | string | 是 | 对话ID | +| | round\_id | string | 是 | 本轮交互的ID | +| | llm\_request\_id | string | 是 | 调用llm的request\_id | +| | text | string | 是 | 系统对外输出的文本,流式全量输出 | +| | spoken | string | 是 | 合成语音时使用的文本,流式全量输出 | +| | finished | bool | 是 | 输出是否结束 | +| | extra\_info | object | 否 | 其他扩展信息,目前支持: - commands: 命令字符串,**此字段为JSON字符串,需要进行二次解析。**各类agent使用的命令字符串可以参考[调用官方Agent](https://help.aliyun.com/zh/model-studio/official-agent)的说明。 - agent\_info: 智能体信息 - tool\_calls: 插件返回的信息 如果没有扩展信息要提交则省略此字段。 | + +示例如下: + +``` +{ + "header": { + "event": "result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output": { + "event": "RespondingContent", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb", + "text": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务,请告诉我更多的细节,我会尽力帮助您。", + "spoken": "您输入了数字序列“12345”。如果您有关于这些数字的问题或者需要我用它们来完成某项任务,请告诉我更多的细节,我会尽力帮助您。", + "finished": true, + "extra_info": { + "commands": "[{\"name\":\"VOLUME_SET\",\"params\":[{\"name\":\"series\",\"normValue\":\"70\",\"value\":\"70\"}]}]", + "tool_calls": [ + { + "id": "", + "type": "function", + "function": { + "name": "function_name", + "arguments": "{\"id\": \"123\", \"name\": \"test\"}", + "outputs": "{\"result\": \"success\"}", + "status": { + "code": 200, + "message": "Success." + } + } + } + ] + } + } + } +} +``` + +### 客户端**更新事件** + +#### **UpdateInfo - Input Message** + +| **一级参数** | **二级参数** | **三级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | --- | +| input | directive | | string | 是 | 指令名称:UpdateInfo | +| | dialog\_id | | string | 否 | 对话ID | +| parameters | images | | list\[\] | 否 | 图片数据 | +| | client\_info | status | object | 否 | 客户端当前状态 | +| | biz\_params | | object | 否 | 与Start消息中biz\_params相同,传递对话系统自定义参数。UpdateInfo指令中biz\_params下面每个子项会全量替换Start指令中biz\_params下面的同名项,并在本次连接后续所有对话中生效。 | + +示例如下: + +``` +{ + "header": { + "action":"continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming":"duplex" + }, + "payload": { + "input":{ + "directive": "UpdateInfo", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + }, + "parameters":{ + "images":[{ + "type": "base64", + "value": "base64String" + }], + "client_info": { + "status": { + "bluetooth_announcement": { + "status": "stopped" + }, + "stream_media_playback": { + "status": "stopped" + }, + "phone_ringing": { + "status": "stopped" + }, + "stream_media_playback_qq": { + "status": "stopped" + } + } + }, + "biz_params":{ + } + } + } +} +``` + +### **心跳事件** + +可以通过定期向服务端发送此消息,避免连接超时断开。考虑到预留网络延迟和处理时间的buffer,建议发送频率50秒一次。服务端会回应相同消息,客户端收到不需要做任何处理,忽略即可。 + +#### **HeartBeat - Input Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| input | directive | string | 是 | 指令名称:**HeartBeat** | +| | dialog\_id | string | 否 | 对话id | + +示例: + +``` +{ + "header": { + "action": "continue-task", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43", + "streaming": "duplex" + }, + "payload": { + "input": { + "directive": "HeartBeat", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +#### **HeartBeat - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | event | string | 是 | 事件名称:**HeartBeat** | +| | dialog\_id | string | 是 | 对话id | + +示例: + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "HeartBeat", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb" + } + } +} +``` + +### **错误事件** + +#### **Error - Output Message** + +| **一级参数** | **二级参数** | **类型** | **是否必选** | **说明** | +| --- | --- | --- | --- | --- | +| output | error\_code | int | 是 | 错误码 | +| output | error\_name | string | 是 | 错误名称 | +| output | error\_message | string | 是 | 错误消息 | + +``` +{ + "header": { + "event":"result-generated", + "task_id": "f894c16f-f20e-4c1d-837e-89e0fbc63a43" + }, + "payload": { + "output":{ + "event": "Error", + "dialog_id": "dd84xxxx-xxxx-xxxx-xxxx-xxxxb7bb", + "error_code": 500, + "error_name": "InternalLLMError", + "error_message": "Internal LLM error" + } + } +} +``` + +### **错误码** + +如遇报错问题,请参见[多模态交互套件-错误码](https://help.aliyun.com/zh/model-studio/multimodal-error-code)进行排查。 + +若问题仍未解决,请联系技术支持,反馈遇到的问题,并提供完整的request\_id和dialog\_id,以便进一步排查问题。 + +## **术语说明** + +**VAD**:Voice Activity Detection,语音活动检测。 + +**ASR**:Automatic Speech Recognition,自动语音识别。 + +**TTS**:Text-to-Speech,文本转语音,语音合成。 + +**LLM**:Large Language Model,大语言模型。 + +本文介绍使用阿里云百炼多模态交互套件可能出现的错误信息及解决方案。 + +## **AccessDenied.Unpurchased** + +``` +{"header":{"task_id":"xxxxx","event":"task-failed","error_code":"AccessDenied.Unpurchased","error_message":"Access to model denied. Please make sure you are eligible for using the model.","attributes":{}},"payload":{}} +``` + +### **Access to model denied. Please make sure you are eligible for using the model.** + +**原因:**错误码error\_code出现在header里,用户未开通阿里云百炼服务,无法建连。 + +**解决方案:**注册或登录阿里云账号,然后前往模型广场开通百炼服务。 + +## **Model.AccessDenied** + +``` +{"header":{"task_id":"xxxxx","event":"task-failed","error_code":"Model.AccessDenied","error_message":"Model access denied.","attributes":{}},"payload":{}} +``` + +### **Model access denied.** + +**原因:** 错误码error\_code出现在header里,使用的业务空间不是默认业务空间,无法建连。目前多模态交互只支持从默认业务空间调用。 + +**解决方案:**使用默认业务空间的API Key调用多模态交互。 + +## **RequestTimeOut** + +``` +{"header":{"task_id":"xxxxx","event":"task-failed","error_code":"ResponseTimeout","error_message":"Response timeout!","attributes":{}},"payload":{}} +``` + +### **Response timeout!** + +**原因:** 错误码error\_code出现在header里,百炼网关报错,无法建连。百炼网关要求服务端和客户端必须持续通信,如果超过1分钟没有交互则会超时报错。 + +**解决方案:** 持续交互,避免长时间无消息传递。若客户端需在无交互时保持连接,应定期发送心跳消息(HeartBeat)。服务端会回应心跳,确保连接活跃,避免超时关闭。具体的心跳消息格式参见[心跳事件](https://help.aliyun.com/zh/model-studio/multimodal-interaction-protocol#df274da95fsoq)。 + +## **421-**InvalidParameter + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":421,"status_name":"InvalidParameter","status_message":"xxxxx"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### **type of directive payload is error, please choose transcript or prompt** + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开,是RequestToRespond的参数type取值错误。 + +**解决方案:**修正RequestToRespond的参数type,重新发请求。type只能支持以下两种: + +(1)transcript 表示直接把文本转语音。 + +(2)prompt 表示把文本送大模型回答。 + +### **status\_message是其他报错信息** + +**原因:**status\_code出现在header里,收到该错误后连接会断开,是其他的参数取值错误 ,status\_message 信息都有具体的提示说明。 + +**解决方案:**根据 status\_message 信息提示修正参数取值。 + +## **422-**DirectiveNotSupported + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":422,"status_name":"DirectiveNotSupported","status_message":"Directive not supported: xxx"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### Directive not supported: xxx + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。传入的指令 directive 的取值是不支持的指令。 + +**解决方案:**请检查指令名称,使用多模态交互可用的指令。参考[文本消息类型](https://help.aliyun.com/zh/model-studio/multimodal-interaction-protocol#15c38d92bc50s)的说明。 + +## **432-**AppConfigError + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":432,"status_name":"AppConfigError","status_message":"xxxxxxx"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。获取到百炼应用的配置时出现问题。 + +**解决方案:**参考status\_message 里的具体信息,修改传入的参数配置。 + +## **433-**BillingAuthError + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":433,"status_name":"BillingAuthError","status_message":"xxxxxxx"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### Billing auth info not found! + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。当前使用的账号未开通百炼多模态交互服务。 + +**解决方案:**为当前账号开通百炼多模态交互服务,或使用已开通的账号。 + +## **444-**ClientAudioTimeout + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":444,"status_name":"ClientAudioTimeout","status_message":"Waiting for client audio timed out."},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### Waiting for client audio timed out. + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。服务端长时间收不到客户端的音频输入。 + +**解决方案:**在duplex模式应持续向服务端上传音频;在tap2talk模式应保证在状态切换到Listening之后立刻持续上传音频,也可以在所有状态下都上传音频;在push2talk模式发送SendSpeech消息后应立刻上传音频直到发送StopSpeech消息。 + +## **449-**TooManyInterrupt + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":449,"status_name":"TooManyInterrupt","status_message":"Send too many RequestToRespond or RequestToSpeak directives in a short time!"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### Send too many RequestToRespond or RequestToSpeak directives in a short time! + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。用户短时间内发送过多RequestToRespond或RequestToSpeek 打断正常交互,通常是调用程序bug导致。 + +**解决方案:**排查程序调用逻辑,避免多次发送RequestToRespond或RequestToSpeek 。 + +## **424-**AudioFormatError + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":424,"status_name":"AudioFormatError","status_message":"xxxxx"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx"}}} +``` + +### Failed to decode audio! Please check audio format! / ASR decode error, please check audio format! + +**原因:**错误码status\_code出现在header里,收到该错误后连接会断开。输入音频的格式不合规,ASR无法正常解析音频。 + +**解决方案:**检查输入的音频格式,输入正确的音频数据。 + +## **425-**NoInputAudioError + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":200,"status_name":"Success","status_message":"Success"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx","round_id":"xxxxx","llm_request_id":"xxxxx","error_code":425,"error_name":"NoInputAudioError","error_message":"ASR input audio error, no input audio , please check audio data!"}}} +``` + +### ASR input audio error, no input audio , please check audio data! + +**原因:**错误码error\_code出现在payload里,收到该错误后连接不会断开。没有获取到有效的输入音频数据,ASR无法识别。 + +**解决方案:**检查是否有音频数据发送,重新输入正确的音频数据。 + +## **426-**InvalidTtsVoice + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":200,"status_name":"Success","status_message":"Success"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx","round_id":"xxxxx","llm_request_id":"xxxxx","error_code":426,"error_name":"InvalidTtsVoice","error_message":"tts voice error , need xxx voice."}}} +``` + +### tts voice error , need xxx voice. + +**原因:**错误码error\_code出现在payload里,收到该错误后连接不会断开。音色参数 voice 取值错误,选择的音色不是当前的语音合成模型支持的音色。 + +**解决方案:**将voice修正为正确的音色。 + +(1)官方音色: + +- 参考官方文档:cosyvoice-v2 / cosyvoice-v3 / cosyvoice-v3-plus / cosyvoice-v3-flash 支持的官方音色参考[音色列表](https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list),qwen-tts-realtime / qwen3-tts 支持的官方音色参考[支持的音色](https://help.aliyun.com/zh/model-studio/qwen-tts-realtime#422789c49bqqx),sambert支持的音色参考[模型列表](https://help.aliyun.com/zh/model-studio/sambert-java-sdk#74cedcb97el0b)(去掉开头的"sambert-"和末尾的"-v1"后就是voice的取值)。 + +- 其他语音合成模型的音色都可以在多模态交互控制台上查看:在左侧**语音交互**配置区域选择对应的语音合成模型,点击右侧**语音交互体验**区域的右上角即可查看可用的音色列表。 + + +(2)复刻音色,确认音色状态为“OK”后才能使用。查询方法参考[查询指定音色](https://help.aliyun.com/zh/model-studio/cosyvoice-clone-api#34490e5a2by7z)。 + +## **451-**NoSpeechRecognized + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":200,"status_name":"Success","status_message":"Success"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx","round_id":"xxxxx","llm_request_id":"xxxxx","error_code":451,"error_name":"NoSpeechRecognized","error_message":"No speech recognized from audio!"}}} +``` + +### No speech recognized from audio! + +**原因:**错误码error\_code出现在payload里,收到该错误后连接不会断开。服务没有识别到用户讲话,通常是push2talk模式下,用户发送了SendSpeech后,没有说话就又发送了StopSpeech指令。其他模式下也有极少数情况是由背景噪音引起。 + +**解决方案:**检查消息发送的逻辑,确认是否有用户说话的音频数据发送到服务端。 + +## **500-InternalSynthesizerError/InternalAsrError /InternalLLMError/LLMTimeoutError** + +``` +{"header":{"event":"result-generated","task_id":"xxxxx","status_code":200,"status_name":"Success","status_message":"Success"},"payload":{"output":{"event":"Error","dialog_id":"xxxxx","round_id":"xxxxx","llm_request_id":"xxxxx","error_code":500,"error_name":"InternalAsrError","error_message":"Internal asr error"}}} +``` + +### Internal synthesizer error/Internal asr error/Internal LLM error/LLM response timeout + +**原因:**错误码error\_code出现在payload里,收到此类错误后连接不会断开。服务内部错误,tts/asr/llm出错。 + +**解决方案:**出现此类错误时,可以重新发起请求来恢复使用。如果需要确认具体原因,请记录出错时完整的request\_id和dialog\_id,联系技术支持。 \ No newline at end of file diff --git a/docs/z-image.md b/docs/z-image.md new file mode 100644 index 0000000..acb34d1 --- /dev/null +++ b/docs/z-image.md @@ -0,0 +1,268 @@ +# Z-Image 文生图 API 指南 + +Z-Image 是一款轻量级文生图模型,支持快速出图、中英文文本渲染,以及多种分辨率和宽高比。 + +## 快速入口 + +- 在线体验(北京): +- 在线体验(新加坡): +- 技术博客: +- 模型列表(按地域): + +## 效果示例 + +### 输入提示词 + +```text +film grain, analog film texture, soft film lighting, Kodak Portra 400 style, +cinematic grainy texture, photorealistic details, subtle noise, (film grain:1.2)。 +采用近景特写镜头拍摄的东亚年轻女性,站在户外雪地中,神情带有轻微惊讶。 +整体画面清新自然,主色调为蓝、白、黑。 +``` + +### 输出图像 + +![Z-Image 输出示例](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6915736671/p1036890.png) + +## 模型概览 + +| 模型名称 | 模型简介 | 输出规格 | +| --- | --- | --- | +| `z-image-turbo` | 轻量模型,快速生图 | 图像格式:PNG;单次固定返回 1 张;总像素范围:`[512*512, 2048*2048]` | + +## 前提条件 + +1. 获取 API Key: +2. 配置环境变量: + +示例: + +```bash +export DASHSCOPE_API_KEY="sk-xxxxxxxx" +``` + +## HTTP 同步调用 + +- 北京地域:`POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` +- 新加坡地域:`POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation` + +### 请求示例 + +`prompt_extend=false` 时响应更快,仅返回图像与提示词; +`prompt_extend=true` 时会返回优化后的提示词和推理过程,但耗时与费用更高。 + +```bash +curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \ + --header 'Content-Type: application/json' \ + --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ + --data '{ + "model": "z-image-turbo", + "input": { + "messages": [ + { + "role": "user", + "content": [ + { + "text": "一只坐在窗边的橘猫,午后阳光,胶片质感,写实风格。" + } + ] + } + ] + }, + "parameters": { + "prompt_extend": false, + "size": "1120*1440" + } + }' +``` + +## 请求参数 + +### Headers + +| 参数 | 类型 | 必选 | 说明 | +| --- | --- | --- | --- | +| `Content-Type` | string | 是 | 固定为 `application/json` | +| `Authorization` | string | 是 | 鉴权信息,格式:`Bearer $DASHSCOPE_API_KEY` | + +### Body + +| 参数路径 | 类型 | 必选 | 说明 | +| --- | --- | --- | --- | +| `model` | string | 是 | 模型名称,固定为 `z-image-turbo` | +| `input` | object | 是 | 输入对象 | +| `input.messages` | array | 是 | 消息数组,仅支持单轮输入 | +| `input.messages[0].role` | string | 是 | 固定为 `user` | +| `input.messages[0].content` | array | 是 | 内容数组,必须且仅能包含 1 个 `text` 对象 | +| `input.messages[0].content[0].text` | string | 是 | 正向提示词(中英文均可),长度上限 800 字符,超长自动截断 | +| `parameters` | object | 否 | 生成参数对象 | +| `parameters.size` | string | 否 | 输出分辨率,格式 `宽*高`,默认 `1024*1536` | +| `parameters.prompt_extend` | bool | 否 | 是否启用提示词智能改写,默认 `false` | +| `parameters.seed` | integer | 否 | 随机种子,范围 `[0, 2147483647]` | + +### size 参数说明 + +- 总像素限制:`[512*512, 2048*2048]` +- 推荐总像素范围:`[1024*1024, 1536*1536]` +- 同一 `seed` 可提升结果稳定性,但不能保证完全一致 + +### 推荐分辨率 + +#### 总像素约 1024x1024 + +| 宽高比 | 分辨率 | +| --- | --- | +| 1:1 | `1024*1024` | +| 2:3 | `832*1248` | +| 3:2 | `1248*832` | +| 3:4 | `864*1152` | +| 4:3 | `1152*864` | +| 7:9 | `896*1152` | +| 9:7 | `1152*896` | +| 9:16 | `720*1280` | +| 9:21 | `576*1344` | +| 16:9 | `1280*720` | +| 21:9 | `1344*576` | + +#### 总像素约 1280x1280 + +| 宽高比 | 分辨率 | +| --- | --- | +| 1:1 | `1280*1280` | +| 2:3 | `1024*1536` | +| 3:2 | `1536*1024` | +| 3:4 | `1104*1472` | +| 4:3 | `1472*1104` | +| 7:9 | `1120*1440` | +| 9:7 | `1440*1120` | +| 9:16 | `864*1536` | +| 9:21 | `720*1680` | +| 16:9 | `1536*864` | +| 21:9 | `1680*720` | + +#### 总像素约 1536x1536 + +| 宽高比 | 分辨率 | +| --- | --- | +| 1:1 | `1536*1536` | +| 2:3 | `1248*1872` | +| 3:2 | `1872*1248` | +| 3:4 | `1296*1728` | +| 4:3 | `1728*1296` | +| 7:9 | `1344*1728` | +| 9:7 | `1728*1344` | +| 9:16 | `1152*2048` | +| 9:21 | `864*2016` | +| 16:9 | `2048*1152` | +| 21:9 | `2016*864` | + +## 响应示例 + +### 成功响应 + +任务数据(如图像 URL)仅保留 24 小时,请及时保存。 + +```json +{ + "output": { + "choices": [ + { + "finish_reason": "stop", + "message": { + "role": "assistant", + "content": [ + { + "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx" + }, + { + "text": "一只坐在窗边的橘猫,午后阳光,胶片质感,写实风格。" + } + ], + "reasoning_content": "" + } + } + ] + }, + "usage": { + "width": 1120, + "height": 1440, + "image_count": 1, + "input_tokens": 0, + "output_tokens": 0, + "total_tokens": 0 + }, + "request_id": "8a0809b4-a796-47f4-a095-394b02b62xxx" +} +``` + +### 失败响应 + +```json +{ + "request_id": "a4d78a5f-655f-9639-8437-xxxxxx", + "code": "InvalidParameter", + "message": "num_images_per_prompt must be 1" +} +``` + +## 响应字段说明 + +| 参数路径 | 类型 | 说明 | +| --- | --- | --- | +| `output` | object | 任务输出信息 | +| `output.choices` | array | 模型输出数组,仅包含 1 个元素 | +| `output.choices[0].finish_reason` | string | 停止原因,正常完成为 `stop` | +| `output.choices[0].message.role` | string | 固定为 `assistant` | +| `output.choices[0].message.content[].image` | string | 生成图像 URL(PNG,24 小时有效) | +| `output.choices[0].message.content[].text` | string | `prompt_extend=false` 返回原提示词;`true` 返回改写后提示词 | +| `output.choices[0].message.reasoning_content` | string | 推理过程,仅 `prompt_extend=true` 时返回 | +| `usage` | object | 统计信息 | +| `usage.width` | integer | 图像宽度(像素) | +| `usage.height` | integer | 图像高度(像素) | +| `usage.image_count` | integer | 图像数量,固定为 1 | +| `usage.input_tokens` | integer | 输入 token 数,`prompt_extend=false` 时固定为 0 | +| `usage.output_tokens` | integer | 输出 token 数,`prompt_extend=false` 时固定为 0 | +| `usage.output_tokens_details.reasoning_tokens` | integer | 推理 token 数,仅 `prompt_extend=true` 时返回 | +| `usage.total_tokens` | integer | 总 token 数,`prompt_extend=false` 时固定为 0 | +| `request_id` | string | 请求唯一标识,可用于排障 | +| `code` | string | 错误码,仅失败时返回 | +| `message` | string | 错误详情,仅失败时返回 | + +## 使用限制 + +- 图像 URL 仅保留 24 小时,请及时下载。 +- 输入 `prompt` 与输出图像均经过内容安全审核,违规请求可能返回 `IPInfringementSuspect` 或 `DataInspectionFailed`。 +- 若业务网络禁止访问公网 OSS,请将下列域名加入白名单: + +```text +dashscope-result-bj.oss-cn-beijing.aliyuncs.com +dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com +dashscope-result-sh.oss-cn-shanghai.aliyuncs.com +dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com +dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com +dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com +dashscope-result-hy.oss-cn-heyuan.aliyuncs.com +dashscope-result-cd.oss-cn-chengdu.aliyuncs.com +dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com +dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com +``` + +## 计费与限流 + +- 模型价格与免费额度: +- 限流说明: +- 计费按成功生成的图像张数统计;失败请求不计费,也不消耗免费额度: + +## 错误码 + +错误码总览: + +## 常见问题 + +### 如何查看模型调用量? + +模型调用约 1 小时后,可在以下页面查看调用次数、成功率等指标: + +- 模型监控(北京): +- 模型监控(新加坡): +- 账单查询与成本管理: diff --git a/main/CMakeLists.txt b/main/CMakeLists.txt new file mode 100644 index 0000000..0784f7b --- /dev/null +++ b/main/CMakeLists.txt @@ -0,0 +1,3 @@ +# Keep `main` as a lightweight component holder for project-wide Kconfig. +# Runtime sources are split into layered components under `components/`. +idf_component_register() diff --git a/main/Kconfig.projbuild b/main/Kconfig.projbuild new file mode 100644 index 0000000..0434daf --- /dev/null +++ b/main/Kconfig.projbuild @@ -0,0 +1,580 @@ +menu "TQ Controller Config" + +config TQ_WIFI_SSID + string "Wi-Fi SSID" + default "" + +config TQ_WIFI_PASSWORD + string "Wi-Fi Password" + default "" + +config TQ_WIFI_MAXIMUM_RETRY + int "Wi-Fi Maximum Retry" + default 10 + +config TQ_WIFI_CONNECT_TIMEOUT_MS + int "Wi-Fi connect timeout (ms)" + range 3000 60000 + default 15000 + +config TQ_LIFECYCLE_START_RETRY_COUNT + int "Lifecycle start retry count" + range 0 5 + default 2 + +config TQ_LIFECYCLE_RETRY_BACKOFF_MS + int "Lifecycle retry base backoff (ms)" + range 100 10000 + default 800 + +config TQ_HTTP_PORT + int "REST HTTP Port" + default 80 + +config TQ_REST_PRINTER_CONNECT_TIMEOUT_MS + int "REST printer connect timeout default (ms)" + range 1000 60000 + default 15000 + +config TQ_REST_LABEL_TIMEOUT_MS + int "REST label/offset timeout default (ms)" + range 500 30000 + default 5000 + +config TQ_REST_OTA_STEP_TIMEOUT_MS + int "REST OTA step timeout default (ms)" + range 500 60000 + default 5000 + +config TQ_PRINTER_CONTROL_LOCK_TIMEOUT_MS + int "Printer control lane lock timeout (ms)" + range 100 5000 + default 1000 + +config TQ_PRINTER_WORKER_QUEUE_WAIT_MS + int "Printer worker queue poll wait (ms)" + range 50 2000 + default 250 + +config TQ_PRINTER_QUEUE_RETRY_DELAY_MS + int "Printer queue retry delay (ms)" + range 5 500 + default 20 + +config TQ_PRINTER_STATUS_POLL_INTERVAL_MS + int "Printer status poll interval (ms)" + range 1000 30000 + default 5000 + +config TQ_PRINTER_STOP_TIMEOUT_MS + int "Printer protocol stop timeout (ms)" + range 1000 30000 + default 8000 + +config TQ_PRINTER_DEFAULT_BACKEND + int "Printer default backend (0=BLE, 1=Direct)" + range 0 1 + default 0 + +config TQ_DIRECT_PRINTER_ENABLE + bool "Enable direct thermal printer backend" + default y + +config TQ_DIRECT_PRINTER_OPERATION_TIMEOUT_MS + int "Direct printer max operation timeout (ms)" + range 1000 300000 + default 90000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_STROBE_ON_US + int "Direct printer strobe on-time (us)" + range 100 10000 + default 1000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_STROBE_INTERVAL_US + int "Direct printer strobe interval (us)" + range 0 10000 + default 200 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_MOTOR_STEP_US + int "Direct printer motor step delay (us)" + range 100 20000 + default 2000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_MOTOR_REVERSE + bool "Direct printer motor direction reversed" + default n + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_STEPS_PER_LINE + int "Direct printer motor steps per printed line" + range 1 8 + default 2 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_GAP_STEPS + int "Direct printer gap move steps" + range 1 2000 + default 96 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_TEMP_MIN_C + int "Direct printer allowed minimum temperature (C)" + range 0 120 + default 15 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_TEMP_MAX_C + int "Direct printer allowed maximum temperature (C)" + range 1 150 + default 55 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_BATTERY_MIN_PERCENT + int "Direct printer minimum battery percent" + range 0 100 + default 5 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_PAPER_PRESENT_LEVEL + int "Direct printer paper-present GPIO level (0/1)" + range 0 1 + default 0 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_BATTERY_EMPTY_MV + int "Direct printer battery empty voltage (mV)" + range 2500 5000 + default 3300 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_BATTERY_FULL_MV + int "Direct printer battery full voltage (mV)" + range 2600 6000 + default 4200 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_BATTERY_DIVIDER_RATIO_X1000 + int "Direct printer battery divider ratio x1000" + range 1000 10000 + default 2000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_NTC_PULLUP_OHMS + int "Direct printer NTC pull-up resistor (ohms)" + range 1000 200000 + default 10000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_NTC_R25_OHMS + int "Direct printer NTC R25 resistance (ohms)" + range 1000 200000 + default 10000 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_DIRECT_PRINTER_NTC_BETA + int "Direct printer NTC beta constant" + range 1000 10000 + default 3950 + depends on TQ_DIRECT_PRINTER_ENABLE + +config TQ_API_KEY + string "REST API Key (optional, empty means disabled)" + default "" + +config TQ_Z_IMAGE_API_KEY + string "Z-Image API Key for DashScope HTTP (optional, fallback to Voice API key)" + default "sk-7a50eca6856d4afb968ac3bf512f6d1b" + +config TQ_Z_IMAGE_API_ENDPOINT + string "Z-Image HTTP endpoint" + default "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" + +config TQ_Z_IMAGE_MODEL + string "Z-Image model" + default "z-image-turbo" + +config TQ_Z_IMAGE_DEFAULT_SIZE + string "Z-Image default output size" + default "512*768" + +config TQ_Z_IMAGE_TIMEOUT_MS + int "Z-Image generation timeout (ms)" + range 5000 180000 + default 45000 + +config TQ_Z_IMAGE_DOWNLOAD_TIMEOUT_MS + int "Z-Image image download timeout (ms)" + range 2000 120000 + default 15000 + +config TQ_Z_IMAGE_MAX_RESPONSE_BYTES + int "Z-Image max response body bytes" + range 1024 262144 + default 65536 + +config TQ_Z_IMAGE_MAX_PNG_BYTES + int "Z-Image max downloaded PNG bytes" + range 65536 8388608 + default 4194304 + +config TQ_Z_IMAGE_HTTP_BUFFER_BYTES + int "Z-Image HTTP client buffer bytes" + range 4096 32768 + default 16384 + +config TQ_Z_IMAGE_HTTP_READ_CHUNK_BYTES + int "Z-Image HTTP stream read chunk bytes" + range 4096 32768 + default 16384 + +config TQ_Z_IMAGE_COEX_PREFER_WIFI_DURING_DOWNLOAD + bool "Prefer Wi-Fi RF during image download" + default y + +config TQ_VOICE_API_KEY + string "Voice API Key for DashScope WebSocket (optional)" + default "sk-7a50eca6856d4afb968ac3bf512f6d1b" + +config TQ_VOICE_WS_URI + string "Voice WebSocket URI" + default "wss://dashscope.aliyuncs.com/api-ws/v1/inference" + +config TQ_VOICE_WORKSPACE_ID + string "Voice workspace_id" + default "llm-igyrxzdvbwja5gyt" + +config TQ_VOICE_APP_ID + string "Voice app_id" + default "106a67b690db4686a5d6b40d119653fa" + +config TQ_VOICE_USER_ID + string "Voice client user_id" + default "esp32-user" + +config TQ_VOICE_DEVICE_UUID + string "Voice client device uuid (optional)" + default "" + +config TQ_VOICE_TTS_VOICE + string "Voice TTS voice (optional)" + default "longling_v3" + +config TQ_VOICE_SAMPLE_RATE + int "Voice sample rate" + range 8000 48000 + default 16000 + +config TQ_VOICE_OPUS_FRAME_MS + int "Voice raw-opus frame size (ms)" + range 10 120 + default 100 + +config TQ_VOICE_OPUS_BITRATE_KBPS + int "Voice raw-opus bitrate (kbps)" + range 6 128 + default 32 + +config TQ_VOICE_HEARTBEAT_SEC + int "Voice heartbeat interval seconds" + range 10 55 + default 50 + +config TQ_VOICE_I2C_PORT + int "Voice I2C port" + range 0 1 + default 1 + +config TQ_VOICE_I2C_SDA_PIN + int "Voice I2C SDA GPIO" + range 0 48 + default 6 + +config TQ_VOICE_I2C_SCL_PIN + int "Voice I2C SCL GPIO" + range 0 48 + default 7 + +config TQ_VOICE_CODEC_ADDR + int "ES8311 I2C address" + range 1 126 + default 48 + +config TQ_VOICE_I2S_PORT + int "Voice I2S port" + range 0 1 + default 0 + +config TQ_VOICE_I2S_MCLK_PIN + int "Voice I2S MCLK GPIO" + range -1 48 + default 38 + +config TQ_VOICE_I2S_BCLK_PIN + int "Voice I2S BCLK GPIO" + range 0 48 + default 39 + +config TQ_VOICE_I2S_WS_PIN + int "Voice I2S WS GPIO" + range 0 48 + default 41 + +config TQ_VOICE_I2S_DOUT_PIN + int "Voice I2S DOUT GPIO" + range 0 48 + default 42 + +config TQ_VOICE_I2S_DIN_PIN + int "Voice I2S DIN GPIO" + range 0 48 + default 40 + +config TQ_VOICE_CODEC_PA_PIN + int "ES8311 PA control GPIO" + range -1 48 + default 20 + +menu "Board GPIO Mapping (ESP32-S3)" + +config TQ_POWER_HOLD_PIN + int "Power hold GPIO (drive high to keep power)" + range -1 48 + default 1 + +config TQ_POWER_KEY_PIN + int "Power key GPIO" + range -1 48 + default 47 + +config TQ_LED_R_PIN + int "LED_R GPIO" + range -1 48 + default 2 + +config TQ_LED_G_PIN + int "LED_G GPIO" + range -1 48 + default 21 + +config TQ_KEY_PRINT_PIN + int "Print confirm key / 7.2V boost control GPIO" + range -1 48 + default 0 + +config TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT + bool "Use KEY_PRINT pin as 7.2V boost enable on boot" + default y + +config TQ_KEY_PRINT_BOOST_ACTIVE_HIGH + bool "KEY_PRINT boost enable level is high" + default y + depends on TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT + +config TQ_MIC_KEY_PIN + int "Mic key GPIO" + range -1 48 + default 14 + +config TQ_BATTERY_ADC_PIN + int "Battery ADC detect GPIO" + range -1 48 + default 15 + +config TQ_NTC_ADC_PIN + int "NTC ADC GPIO" + range -1 48 + default 18 + +config TQ_PRINT_STB_56_PIN + int "Printer STB5_6 GPIO" + range -1 48 + default 4 + +config TQ_PRINT_STB_34_PIN + int "Printer STB3_4 GPIO" + range -1 48 + default 5 + +config TQ_PRINT_STB_12_PIN + int "Printer STB1_2 GPIO" + range -1 48 + default 16 + +config TQ_PRINT_PAPER_PIN + int "Printer paper detect GPIO" + range -1 48 + default 17 + +config TQ_PRINT_OUTA_P_PIN + int "Printer OUTA+ GPIO" + range -1 48 + default 8 + +config TQ_PRINT_OUTA_N_PIN + int "Printer OUTA- GPIO" + range -1 48 + default 19 + +config TQ_PRINT_OUTB_P_PIN + int "Printer OUTB+ GPIO" + range -1 48 + default 3 + +config TQ_PRINT_OUTB_N_PIN + int "Printer OUTB- GPIO" + range -1 48 + default 46 + +config TQ_PRINT_LAT_PIN + int "Printer LAT GPIO" + range -1 48 + default 45 + +config TQ_SPI_SHARED_MOSI_PIN + int "Printer/Screen shared MOSI GPIO" + range -1 48 + default 9 + +config TQ_PRINTER_MISO_PIN + int "Printer MISO GPIO" + range -1 48 + default 10 + +config TQ_SPI_SHARED_CLK_PIN + int "Printer/Screen shared CLK GPIO" + range -1 48 + default 11 + +config TQ_SCREEN_DC_PIN + int "Screen DC GPIO" + range -1 48 + default 12 + +config TQ_SCREEN_CS_PIN + int "Screen CS GPIO" + range -1 48 + default 13 + +config TQ_SCREEN_BACKLIGHT_PIN + int "Screen backlight GPIO (active high)" + range -1 48 + default 48 + +endmenu + +menu "ST7789 Screen" + +config TQ_SCREEN_ENABLE + bool "Enable ST7789 screen driver" + default y + depends on SOC_GPSPI_SUPPORTED + +config TQ_SCREEN_TEST_PATTERN_ON_BOOT + bool "Show ST7789 test pattern at boot" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_PIXEL_CLOCK_HZ + int "ST7789 SPI pixel clock (Hz)" + range 1000000 80000000 + default 10000000 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_H_RES + int "ST7789 horizontal resolution" + range 64 480 + default 320 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_V_RES + int "ST7789 vertical resolution" + range 64 480 + default 240 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_DRAW_LINES + int "ST7789 draw chunk lines" + range 1 120 + default 20 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_SPI_MODE + int "ST7789 SPI mode (0-3)" + range 0 3 + default 0 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_COLOR_ORDER_BGR + bool "ST7789 color order is BGR" + default n + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_INVERT_COLOR + bool "ST7789 invert color" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_SWAP_COLOR_BYTES + bool "ST7789 swap color bytes" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH + bool "ST7789 backlight active-high" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_MIRROR_X + bool "ST7789 mirror X axis" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_MIRROR_Y + bool "ST7789 mirror Y axis" + default n + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_SWAP_XY + bool "ST7789 swap X/Y axis" + default y + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_X_GAP + int "ST7789 X gap" + range 0 480 + default 0 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_Y_GAP + int "ST7789 Y gap" + range 0 480 + default 0 + depends on TQ_SCREEN_ENABLE + +config TQ_SCREEN_RESET_PIN + int "ST7789 reset GPIO (-1 if not connected)" + range -1 48 + default -1 + depends on TQ_SCREEN_ENABLE + +endmenu + +config TQ_VOICE_CODEC_PA_PIN_REVERSED + bool "ES8311 PA enable level is active-low" + default n + +config TQ_VOICE_CODEC_OUT_VOL + int "ES8311 output volume (0-100)" + range 0 100 + default 70 + +config TQ_VOICE_CODEC_MIC_GAIN_DB + int "ES8311 mic gain dB" + range 0 42 + default 24 + +endmenu diff --git a/main/idf_component.yml b/main/idf_component.yml new file mode 100644 index 0000000..b3308cf --- /dev/null +++ b/main/idf_component.yml @@ -0,0 +1,21 @@ +## IDF Component Manager Manifest File +dependencies: + ## Required IDF version + idf: + version: '>=4.1.0' + # # Put list of dependencies here + # # For components maintained by Espressif: + # component: "~1.0.0" + # # For 3rd party components: + # username/component: ">=1.0.0,<2.0.0" + # username2/component2: + # version: "~1.0.0" + # # For transient dependencies `public` flag can be set. + # # `public` flag doesn't have an effect dependencies of the `main` component. + # # All dependencies of `main` are public by default. + # public: true + espressif/esp_websocket_client: ^1.6.1 + espressif/esp_codec_dev: ^1.5.4 + espressif/esp_audio_codec: ^2.4.1 + espressif/libpng: ^1.6.55 + lvgl/lvgl: ^8.3.11 diff --git a/partitions.csv b/partitions.csv new file mode 100644 index 0000000..c721d7e --- /dev/null +++ b/partitions.csv @@ -0,0 +1,4 @@ +# Name, Type, SubType, Offset, Size, Flags +nvs, data, nvs, , 0x6000, +phy_init, data, phy, , 0x1000, +factory, app, factory, , 4M, diff --git a/sdkconfig.defaults b/sdkconfig.defaults new file mode 100644 index 0000000..7071698 --- /dev/null +++ b/sdkconfig.defaults @@ -0,0 +1,107 @@ +CONFIG_IDF_TARGET="esp32s3" +CONFIG_BT_ENABLED=y +CONFIG_BT_NIMBLE_ENABLED=y +CONFIG_BT_BLUEDROID_ENABLED=n +CONFIG_BT_NIMBLE_ROLE_CENTRAL=y +CONFIG_BT_NIMBLE_ATT_PREFERRED_MTU=247 +# CONFIG_ESP_WIFI_SOFTAP_SUPPORT is not set +CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE=n +CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=24 +CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=256 +CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM=32 +CONFIG_ESP_WIFI_CACHE_TX_BUFFER_NUM=64 +CONFIG_ESP_WIFI_TX_BA_WIN=16 +CONFIG_ESP_WIFI_RX_BA_WIN=32 +CONFIG_LWIP_WND_SCALE=y +CONFIG_LWIP_TCP_RCV_SCALE=3 +CONFIG_LWIP_TCP_SND_BUF_DEFAULT=57344 +CONFIG_LWIP_TCP_WND_DEFAULT=262144 +CONFIG_LWIP_TCP_RECVMBOX_SIZE=192 +CONFIG_LWIP_TCPIP_RECVMBOX_SIZE=256 +CONFIG_TQ_WIFI_SSID="TalkingQ" +CONFIG_TQ_WIFI_PASSWORD="TalkingQ123" +CONFIG_TQ_Z_IMAGE_DEFAULT_SIZE="512*768" +CONFIG_TQ_Z_IMAGE_HTTP_BUFFER_BYTES=16384 +CONFIG_TQ_Z_IMAGE_HTTP_READ_CHUNK_BYTES=16384 +CONFIG_TQ_Z_IMAGE_COEX_PREFER_WIFI_DURING_DOWNLOAD=y +# CONFIG_PARTITION_TABLE_SINGLE_APP_LARGE is not set +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" +CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y +CONFIG_ESPTOOLPY_FLASHSIZE="16MB" + +# ESP32-S3-WROOM-1-N16R8: 16MB Quad Flash + 8MB Octal PSRAM +CONFIG_SPIRAM=y +CONFIG_SPIRAM_MODE_OCT=y +CONFIG_SPIRAM_TYPE_AUTO=y +CONFIG_SPIRAM_SPEED_80M=y +CONFIG_SPIRAM_BOOT_INIT=y +CONFIG_SPIRAM_USE_MALLOC=y +CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP=y +CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY=y +CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=y +CONFIG_TQ_VOICE_API_KEY="sk-7a50eca6856d4afb968ac3bf512f6d1b" +CONFIG_TQ_VOICE_WS_URI="wss://dashscope.aliyuncs.com/api-ws/v1/inference" +CONFIG_TQ_VOICE_WORKSPACE_ID="llm-igyrxzdvbwja5gyt" +CONFIG_TQ_VOICE_APP_ID="106a67b690db4686a5d6b40d119653fa" +CONFIG_TQ_VOICE_USER_ID="esp32-user" +CONFIG_TQ_VOICE_DEVICE_UUID="" +CONFIG_TQ_VOICE_TTS_VOICE="longling_v3" +CONFIG_TQ_VOICE_SAMPLE_RATE=16000 +CONFIG_TQ_VOICE_OPUS_FRAME_MS=100 +CONFIG_TQ_VOICE_OPUS_BITRATE_KBPS=32 +CONFIG_TQ_VOICE_HEARTBEAT_SEC=50 +CONFIG_TQ_VOICE_I2C_PORT=1 +CONFIG_TQ_VOICE_I2C_SDA_PIN=6 +CONFIG_TQ_VOICE_I2C_SCL_PIN=7 +CONFIG_TQ_VOICE_CODEC_ADDR=48 +CONFIG_TQ_VOICE_I2S_PORT=0 +CONFIG_TQ_VOICE_I2S_MCLK_PIN=38 +CONFIG_TQ_VOICE_I2S_BCLK_PIN=39 +CONFIG_TQ_VOICE_I2S_WS_PIN=41 +CONFIG_TQ_VOICE_I2S_DOUT_PIN=42 +CONFIG_TQ_VOICE_I2S_DIN_PIN=40 +CONFIG_TQ_VOICE_CODEC_PA_PIN=20 +CONFIG_TQ_VOICE_CODEC_OUT_VOL=70 +CONFIG_TQ_VOICE_CODEC_MIC_GAIN_DB=24 +CONFIG_TQ_POWER_HOLD_PIN=1 +CONFIG_TQ_POWER_KEY_PIN=47 +CONFIG_TQ_LED_R_PIN=2 +CONFIG_TQ_LED_G_PIN=21 +CONFIG_TQ_KEY_PRINT_PIN=0 +CONFIG_TQ_KEY_PRINT_BOOST_ENABLE_ON_BOOT=y +CONFIG_TQ_KEY_PRINT_BOOST_ACTIVE_HIGH=y +CONFIG_TQ_MIC_KEY_PIN=14 +CONFIG_TQ_BATTERY_ADC_PIN=15 +CONFIG_TQ_NTC_ADC_PIN=18 +CONFIG_TQ_PRINT_STB_56_PIN=4 +CONFIG_TQ_PRINT_STB_34_PIN=5 +CONFIG_TQ_PRINT_STB_12_PIN=16 +CONFIG_TQ_PRINT_PAPER_PIN=17 +CONFIG_TQ_PRINT_OUTA_P_PIN=8 +CONFIG_TQ_PRINT_OUTA_N_PIN=19 +CONFIG_TQ_PRINT_OUTB_P_PIN=3 +CONFIG_TQ_PRINT_OUTB_N_PIN=46 +CONFIG_TQ_PRINT_LAT_PIN=45 +CONFIG_TQ_SPI_SHARED_MOSI_PIN=9 +CONFIG_TQ_PRINTER_MISO_PIN=10 +CONFIG_TQ_SPI_SHARED_CLK_PIN=11 +CONFIG_TQ_SCREEN_DC_PIN=12 +CONFIG_TQ_SCREEN_CS_PIN=13 +CONFIG_TQ_SCREEN_BACKLIGHT_PIN=48 +CONFIG_TQ_SCREEN_ENABLE=y +CONFIG_TQ_SCREEN_TEST_PATTERN_ON_BOOT=y +CONFIG_TQ_SCREEN_PIXEL_CLOCK_HZ=10000000 +CONFIG_TQ_SCREEN_H_RES=320 +CONFIG_TQ_SCREEN_V_RES=240 +CONFIG_TQ_SCREEN_DRAW_LINES=20 +CONFIG_TQ_SCREEN_SPI_MODE=0 +# CONFIG_TQ_SCREEN_COLOR_ORDER_BGR is not set +CONFIG_TQ_SCREEN_INVERT_COLOR=y +CONFIG_TQ_SCREEN_SWAP_COLOR_BYTES=y +CONFIG_TQ_SCREEN_BACKLIGHT_ACTIVE_HIGH=y +CONFIG_TQ_SCREEN_MIRROR_X=y +CONFIG_TQ_SCREEN_SWAP_XY=y +CONFIG_TQ_SCREEN_X_GAP=0 +CONFIG_TQ_SCREEN_Y_GAP=0 +CONFIG_TQ_SCREEN_RESET_PIN=-1 diff --git a/tools/gen_cn16_font.py b/tools/gen_cn16_font.py new file mode 100644 index 0000000..e6e17fa --- /dev/null +++ b/tools/gen_cn16_font.py @@ -0,0 +1,130 @@ +#!/usr/bin/env python3 +""" +Generate compact Chinese 16x16 bitmap font assets for ESP32 firmware. + +Output: + - main/domain/assets/fonts/cn16_index.bin (entry: uint32 codepoint + uint16 glyph_id, little-endian) + - main/domain/assets/fonts/cn16_glyphs.bin (glyph bytes, 32 bytes per glyph, row-major, MSB-left) + +Glyph set: + All valid single-character GB2312 code points. +""" + +from __future__ import annotations + +import argparse +import struct +from pathlib import Path + +from PIL import Image, ImageDraw, ImageFont + + +def default_out_dir() -> Path: + repo_root = Path(__file__).resolve().parent.parent + return repo_root / "main" / "domain" / "assets" / "fonts" + + +def iter_gb2312_codepoints(): + seen = set() + for hi in range(0xA1, 0xFF): + for lo in range(0xA1, 0xFF): + bs = bytes((hi, lo)) + try: + ch = bs.decode("gb2312") + except UnicodeDecodeError: + continue + if len(ch) != 1: + continue + cp = ord(ch) + if cp in seen: + continue + seen.add(cp) + yield cp + + +def render_glyph_16(font: ImageFont.FreeTypeFont, cp: int) -> bytes: + ch = chr(cp) + img = Image.new("L", (16, 16), color=255) + draw = ImageDraw.Draw(img) + + # Center glyph in 16x16 cell. + bbox = draw.textbbox((0, 0), ch, font=font) + if bbox is None: + bbox = (0, 0, 0, 0) + x0, y0, x1, y1 = bbox + w = x1 - x0 + h = y1 - y0 + + draw_x = (16 - w) // 2 - x0 + draw_y = (16 - h) // 2 - y0 + draw.text((draw_x, draw_y), ch, font=font, fill=0) + + # Convert to 1bpp packed rows, MSB-left. + px = img.load() + out = bytearray() + for y in range(16): + row_bits = 0 + for x in range(16): + bit = 1 if px[x, y] < 128 else 0 + row_bits = (row_bits << 1) | bit + out.append((row_bits >> 8) & 0xFF) + out.append(row_bits & 0xFF) + return bytes(out) + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument( + "--font", + default="app/src/main/assets/fonts/msyh.ttc", + help="Source CJK font path (TTF/TTC/OTF)", + ) + parser.add_argument( + "--font-index", + type=int, + default=0, + help="TTC face index", + ) + parser.add_argument( + "--out-dir", + default=str(default_out_dir()), + help="Output directory (default: /main/domain/assets/fonts)", + ) + args = parser.parse_args() + + font_path = Path(args.font).resolve() + if not font_path.exists(): + raise FileNotFoundError(f"font not found: {font_path}") + + out_dir = Path(args.out_dir).resolve() + out_dir.mkdir(parents=True, exist_ok=True) + index_path = out_dir / "cn16_index.bin" + glyph_path = out_dir / "cn16_glyphs.bin" + + font = ImageFont.truetype(str(font_path), 16, index=args.font_index) + + codepoints = sorted(iter_gb2312_codepoints()) + glyphs = [] + index_entries = [] + + for gid, cp in enumerate(codepoints): + glyph = render_glyph_16(font, cp) + glyphs.append(glyph) + index_entries.append((cp, gid)) + + with open(index_path, "wb") as f: + for cp, gid in index_entries: + f.write(struct.pack("