# 犀客 X1 固件刷入演示包

版本：`XK-1.8.0-ota-alpha.24`。打包日期：2026-11-03。

这是设备最后一次成功 OTA 安装记录对应的版本；它在 alpha.23 的相同功能源码基础上，仅提高了版本号。适用硬件仅限微雪 Waveshare ESP32-S3-RLCD-4.2 / 犀客 X1，16 MB Flash、8 MB PSRAM、400 × 300 全反射 RLCD。**不要刷进 ESP32-C3、普通 ESP32-S3 开发板或其他电子墨水屏。**

## 最适合演示的流程

1. 先展示整机和屏幕，在电脑打开官网的独立“固件下载”页面。
2. 下载并解压本包；不要直接在 ZIP 压缩窗口里运行脚本。
3. 用支持数据传输的 USB-C 线连接电脑。只供电的线无法刷机。
4. 先长按 **PWR** 关机，按住 **BOOT** 再单击 **PWR** 上电，连接 USB 后松开 BOOT。若没有装电池，也可断开 USB、按住 BOOT 再接入 USB。板上三键是 BOOT、PWR、KEY，不需要寻找不存在的 RESET 键。
5. Mac 双击 `Start-Mac.command`；Windows 双击 `Start-Windows.bat`。Windows 10/11：解压后双击 Start-Windows.bat，脚本会复用可用的 Python 3.9+；没有时联网下载并校验 Python 官方安装器，为当前用户安装，再创建虚拟环境并安装 esptool。Mac 仍需预装 Python 3.9+。
6. 在工具中选择对应 USB 端口，核对硬件。只有输入大写 `FLASH` 才会开始。直接回车即取消。
7. 等待进度、校验和重启提示。写入时不要拔线。完成后关闭工具；如果仍在下载模式，松开 BOOT，用 PWR 关机再开机。保持供电至少 90 秒，不要反复开关串口。
8. 按设备屏幕提示连接配网热点，打开 `http://192.168.4.1`，选择 2.4 GHz Wi-Fi 并保存。当前构建热点格式为 `WeatherClock-XXXX`，出厂热点密码 `12345678`；以屏幕显示为准。可关闭手机蜂窝网络/VPN后重试配网页面。
9. 展示九页切换、天气同步及“你好小智”语音对话。新机配网后，如小智提示激活，记下设备显示或播报的 6 位验证码，到小智官方控制台（xiaozhi.me）登录，在「智能体 → 添加设备」输入验证码。犀客官网暂不支持代绑定。 当前为开发演示，暂不开放下单、付款或订金。小智语音依赖第三方官方服务，需用户自行注册和绑定；犀客不随硬件提供云服务权益，也不承诺联网即用。Phone Agent 还需要手机配套 App、蓝牙配对、辅助触控及共享屏幕，不能只刷固件就控制手机。

## 重要：首次安装会清除原设备配置

本包的 `xike-x1-alpha24-factory.bin` 是**首次安装/恢复出厂用途的 16 MB 合并镜像**，刷入地址 `0x0`。它不含任何人的 NVS 配置，但写入时会覆盖目标板上原来的 Wi-Fi、蓝牙配对、绑定、自定义资源和设置。务必先征得设备持有人的同意。

已有正常使用的犀客设备应优先使用 OTA，而不是拿这个整包重刷。`xike-x1-alpha24-app.bin` 仅用于高级恢复/发布，不要把它当作 `0x0` 整包；在双 OTA 分区设备上盲写单一应用地址不保证切到新固件。

## 也可以用 Espressif 图形烧录工具

芯片选 `ESP32-S3`，SPI 模式 `DIO`，频率 `80 MHz`，Flash `16 MB`，波特率 `460800`。只勾选 `firmware/xike-x1-alpha24-factory.bin`，地址填 `0x0`。烧录完成须看到成功/校验结果，再重启。不要同时选应用分包和合并包。

官方工具参考：https://docs.espressif.com/projects/esptool/en/latest/esp32s3/esptool/basic-commands.html
板卡说明：https://docs.waveshare.net/ESP32-S3-RLCD-4.2/

## 此版本包含

- 九个工作页面：天气时钟、图片时钟、天气看板、温湿时钟、日历、温湿历史、小智 AI、音乐、Phone Agent。
- 原有小智声音/模型接入、音乐确认流程、天气服务及多页面功能。
- OTA 更新先显示“立即升级 / 稍后”，默认“稍后”。KEY 切换、BOOT 确认；60 秒不操作不会升级。已实机验证“稍后”正常返回。
- 接近满电时稳定显示 100% 的估算电量规则。电量与充电图标是软件估算，不代表精密电量计或硬件充满检测。

## 公共固件与服务边界

包内不含个人 Wi-Fi、蓝牙配对、账号绑定、设备 OTA 密钥、天气密钥、百炼密钥或服务器私钥。天气/音乐等联网能力仍依赖服务端可用性；官方小智服务及手机 App 有各自的激活/配置要求。

### 操控手机：用户必须自行配置 API Key

Phone Agent 的视觉理解由手机 App 调用模型，ESP32-S3 只负责接收任务与执行蓝牙控制。本包不附带手机 App 的个人配置、模型 Key 或演示机的私有网关凭据，也不提供共享百炼额度。

用户需要在自己的 Phone Agent App 中填写：支持图像输入的模型服务接口、模型名称，以及**用户本人申请的 API Key**。保存并完成连通性检查后，再按 App 提示同意截图/指令发送、共享整屏、配对蓝牙并启用辅助触控。手机截图与指令会发送给用户选择的服务商，调用费用由该用户自己的账户承担。未配置自己的 Key 时，不能完成 AI 识屏与自主操控；单纯蓝牙连接不需要大模型 Key。

不要把模型 Key 写进公开固件、博客、截图、演示视频或可公开下载的配置文件。也不要复制现有演示手机的私有配置给他人。此次打包不修改原演示手机的设置。

新板的远程 OTA 需要单独登记并安全配置该设备自己的授权凭据；公开固件不会复制演示机的私有 OTA 身份。因此“刷入公共包”和“已获得该设备的远程 OTA 授权”不是一回事。

## 截图与验证范围

`screenshots` 中是 400 × 300 固件模拟器页面截图，含示例日期、城市、温湿度、歌曲/连接状态，不是整机实拍或实时服务数据。页面说明和截图来源随包保留。

应用 alpha.24 已在演示机完成 OTA 和启动验证。本包复用其相同应用字节；合并镜像的地址、大小、校验值、空 NVS 和应用一致性另行验证。为了不清除演示机的数据，打包时没有对当前演示机执行出厂重刷；新板首刷和 Windows 真机操作仍需在演示时核验。

## 校验与排错

不接设备即可运行：`python3 flash.py --check`。Windows 使用 `py -3 flash.py --check`。

- 找不到端口：换数据线、换 USB 口、关闭其他串口程序，再进入 BOOT 下载模式。
- Windows 自动安装失败：先检查 python.org 和 PyPI 是否能访问；也可从 https://www.python.org/downloads/windows/ 安装 Python 3.9+，再重新运行批处理。
- 校验失败：停止刷入并重新下载，不要绕过校验。
- 写入失败：保持供电，重新进入下载模式；必要时用较低波特率 `115200` 重试。
- 关机不等于断电；屏幕保留画面不代表固件仍在运行。刷机期间必须稳定供电。

请保留 `licenses` 中的上游与字体许可说明。固件使用开源组件，不代表附带第三方云服务的永久免费承诺。