diff --git a/AGENTS.md b/AGENTS.md index 49817d8..76d6fab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,15 +25,23 @@ 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: +Activate ESP-IDF v5.5.3 before running any `idf.py` command: ```bash export PATH=/opt/homebrew/bin:$PATH -export IDF_PATH=/Users/moyyang/esp/v5.5.2/esp-idf +export IDF_PATH=/Users/moyyang/.espressif/v5.5.3/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 build`: compile and validate; generated flash maps and binaries stay under `build/`. +- Secured/provisioned boards with Secure Boot and Flash Encryption enabled must use encrypted app-only flashing: +```bash +idf.py -p encrypted-app-flash +idf.py -p monitor +``` + This updates only the encrypted app partition at `0x30000` via `build/encrypted_app-flash_args`; it must not rewrite the bootloader, partition table, or OTA data on secured boards. +- Do not use `idf.py flash` on secured boards. It attempts to write low flash regions such as the bootloader at `0x0`, which Secure Boot blocks to protect the device. +- Do not use plain `idf.py app-flash` on Flash Encryption boards. It writes a plaintext app image and can boot-fail with invalid app magic or no bootable app partition. +- `idf.py -p flash monitor` is only for fresh development boards without Secure Boot/Flash Encryption, or for initial factory provisioning handled by `tools/esptool-factory`. - `idf.py menuconfig`: adjust project options. - `idf.py fullclean && idf.py build`: clear stale artifacts. @@ -46,8 +54,12 @@ source $IDF_PATH/export.sh ## 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. +- Secured-board flash check: `idf.py -p encrypted-app-flash`, then `idf.py -p monitor`. +- Monitor boot logs should show Secure Boot signature verification, app ESP-IDF version, Wi-Fi connection/IP when configured, printer protocol initialization, `MIC_KEY` readiness, control-plane lifecycle start, and `TQ printer runtime started`. +- If STA connects, confirm host reachability with `ping `. +- For unprovisioned devices, validate the SoftAP provisioning flow at `http://192.168.4.1` and the provisioning endpoints `/`, `/scan`, and `/provision`. +- Physical smoke tests should cover `MIC_KEY` press/release, POWER key long press, and one normal product print flow when the required printer hardware/workflow is available. +- For Control Plane or protocol changes, include one lifecycle or request/response scenario in PR notes. ## Commit & Pull Request Guidelines Use a clear conventional format: diff --git a/README.md b/README.md index 5e6f737..ddf43bd 100644 --- a/README.md +++ b/README.md @@ -58,13 +58,13 @@ ## 构建环境 -本项目按当前实际使用 ESP-IDF `v5.5.2`。 +本项目按当前实际使用 ESP-IDF `v5.5.3`。 先激活环境: ```bash export PATH=/opt/homebrew/bin:$PATH -export IDF_PATH=/Users/moyyang/esp/v5.5.2/esp-idf +export IDF_PATH=/Users/moyyang/.espressif/v5.5.3/esp-idf source $IDF_PATH/export.sh ``` diff --git a/dependencies.lock b/dependencies.lock index b17029a..78b5229 100644 --- a/dependencies.lock +++ b/dependencies.lock @@ -80,7 +80,7 @@ dependencies: idf: source: type: idf - version: 5.5.2 + version: 5.5.3 direct_dependencies: - espressif/button - espressif/esp_audio_codec diff --git a/sdkconfig.defaults b/sdkconfig.defaults index 9656086..dbe5ee9 100644 --- a/sdkconfig.defaults +++ b/sdkconfig.defaults @@ -14,8 +14,8 @@ 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_LOG_DEFAULT_LEVEL_WARN=y -CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y +CONFIG_LOG_DEFAULT_LEVEL_INFO=y +CONFIG_BOOTLOADER_LOG_LEVEL_INFO=y CONFIG_TQ_WIFI_PROV_SOFTAP_SSID="TalkingQ-Setup" CONFIG_TQ_WIFI_PROV_SOFTAP_PASSWORD="" CONFIG_TQ_WIFI_PROV_SOFTAP_CHANNEL=1