@yee94/qk80mk2 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 — 2026-10-18
+
+- Direct USB CDC static theme (`ABKT`) and custom image (`ABKG`) uploads.
+- 320×172 RGB565 encoding, verified against the bundled official WASM.
+- Device detection, response validation, fragmented-read buffering and exclusive port access.
+- No-flow pacing (6 ms), drain and settle (2 s), timeout and cancellation handling.
+- JSON CLI output and ESM API for image encoding and upload.
+- Complete official WASM/JS/config snapshot with source URLs and checksums.
+- Physical theme upload verified by the user on macOS, Node.js 24, firmware v1.1.1.

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License — original project code only
+
+Copyright (c) 2026 yee.wang
+
+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.
+
+Third-party material in reference/official-assets/ is excluded from this MIT
+grant. Its rights remain with its respective owners. See THIRD_PARTY_NOTICES.md
+and reference/LICENSE.via-app for upstream provenance and licensing information.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# @yee94/qk80mk2 — QK80 MK2 Node.js 图片替换工具
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+直接通过 USB CDC 上传主题图片，无浏览器、HTTP 服务、Python或 WASM 运行依赖。
+WASM 只用于开发阶段的离线一致性校验。
+
+- GitHub：https://github.com/yee94/qk80mk2-node
+- npm：https://www.npmjs.com/package/@yee94/qk80mk2
+- CLI：`qk80-screen`；版本：`0.1.0`
+- 完整官方 WASM、JS 与设备配置随 Git 仓库及 npm 包分发，无需额外下载。
+
+## 快速开始：直接使用 npx（推荐）
+
+**无需克隆仓库或全局安装。**准备 Node.js 22+，USB 数据线连接键盘，
+关闭占用串口的官网配置器，即可执行：
+
+```sh
+# 查看连接的键盘
+npx --yes @yee94/qk80mk2 devices
+
+# 将图片替换为键盘主题（默认 ABKT）
+npx --yes @yee94/qk80mk2 upload ./photo.png
+
+# 上传到 Custom Animation 页面（ABKG）
+npx --yes @yee94/qk80mk2 upload ./photo.png --target custom
+
+# 只编码，不访问键盘
+npx --yes @yee94/qk80mk2 encode ./photo.png --out ./theme.abkt
+
+# 帮助与版本
+npx --yes @yee94/qk80mk2 --help
+npx --yes @yee94/qk80mk2 --version
+```
+
+图片路径相对**当前工作目录**，包含空格时请加引号。
+包只有一个可执行入口 `qk80-screen`，npx 会自动选择，不需要额外写命令名。
+首次运行会下载并缓存 npm 包及原生依赖；无需浏览器或本地 HTTP 服务。
+
+如果机器默认使用内网镜像，请显式指定外网源：
+
+```sh
+npx --yes --registry=https://registry.npmjs.org/ @yee94/qk80mk2 upload "./my photo.png"
+```
+
+自动化建议锁定版本并读取 JSON 输出：
+
+```sh
+npx --yes --registry=https://registry.npmjs.org/ @yee94/qk80mk2@0.1.0 upload ./photo.png --json
+```
+
+`--yes`、`--registry` 属于 npx 参数，写在包名前；`--target`、`--json` 等工具参数写在包名后。
+以上外网命令需 npm 发布完成后才可使用；源码仓库可直接运行 `node src/cli.js`。
+
+## 能力列表
+
+| 能力 | 支持情况 |
+| --- | --- |
+| 320×172 静态主题图片替换 | 支持，ABKT，实机确认 |
+| Custom Animation 页面静态图片 | 支持编码/CDC 上传，ABKG；不是动态 GIF |
+| 图片方向、缩放、居中裁剪、透明背景 | 支持，输出 RGB565 |
+| PNG/JPEG 等静态图片输入 | 支持 sharp 可解码的静态格式 |
+| 离线编码 / 已编码文件上传 | 支持，不依赖外部 API 服务 |
+| USB 设备发现 / 指定端口 | 支持，VID 514b / PID 4d02 |
+| 流控、回包检查、限速、超时、取消 | 支持 |
+| JS ESM API / JSON CLI 输出 | 支持，适合脚本及外部定时调度 |
+| 官方 WASM 一致性校验 | 支持，完整资源已包含 |
+| 蓝牙 / 2.4GHz 图片上传 | 未实现、未验证 |
+| 动画/GIF、灯光、按键、固件升级 | 本项目不提供 |
+| 屏幕实时视频流 / 渲染成功回读 | 不支持；这是静态文件上传 |
+
+## 固件与兼容性
+
+| 项目 | 已验证 / 要求 |
+| --- | --- |
+| 键盘 | Qwertykeys QK80 MK2，LCD 320×172 |
+| 主板 Master 固件 | v1.1.1（2025-03-21），此前读取版本字段为 `0x0111` |
+| 屏幕 PLC 固件 | 用户安装配套 v1.1.1 后完成实机验证；未单独回读 PLC 版本 |
+| 老版本 | v1.0.3 的早期尝试曾被拒绝；本项目不保证兼容 |
+| 系统与运行时 | macOS + Node.js 24 实机通过；声明 Node.js ≥22 |
+| Linux / Windows / Bun | 尚未实机验证；建议使用 Node.js |
+| 连接 | USB 有线；自动更新期间需保持 USB 连接 |
+
+官方固件入口：[Firmware and Software](https://www.qwertykeys.com/pages/fw)，选择 **QK80 MK2**。
+已验证配套文件为 `qk80mk2_master_v1.1.1_20250321_*.uf2` 与
+`qk80mk2_plc_v1.1.1_20250321_*.uf2`。本项目包含的是编码 WASM，不包含或刷写固件。
+
+## 实机验证
+
+2026-10-18，macOS / Node.js 24 / QK80 MK2 v1.1.1：
+
+- Node 将静态 PNG 编码为主题 `ABKT`。
+- `ABKT` 和 `ABKG` 都与官网 WASM **110,100 字节完全一致**。
+- USB 串口上传，设备返回 `flowControl=false`。
+- 默认每包间隔 6 ms，发送排空后保持连接 2 秒。
+- **用户确认主题正确显示，并且没有卡在 loading。**
+
+这是静态图片替换，不是视频流。传输时可能短暂出现 loading。
+
+## 其他安装方式
+
+需要 Node.js 22+，已验证 Node.js 24。使用 Node 而非 Bun 执行原生串口依赖。
+
+```sh
+npm install -g @yee94/qk80mk2 --registry=https://registry.npmjs.org/
+qk80-screen --version
+qk80-screen devices
+qk80-screen upload /absolute/path/photo.png
+```
+
+从源码安装（以下开发命令在仓库根目录运行）：
+
+```sh
+git clone https://github.com/yee94/qk80mk2-node.git
+cd qk80mk2-node
+npm ci
+node src/cli.js devices
+```
+
+已安装的 CLI 与 `node src/cli.js` 接收相同参数。
+
+USB 数据线连接键盘，关闭官网配置器对串口的连接。
+根据 VID `514b` / PID `4d02` 自动检测；找到多台时必须传入 `--port`。
+系统串口排他锁避免同时上传。
+
+## 常用命令
+
+### 替换主题图片（默认）
+
+```sh
+npx --yes @yee94/qk80mk2 upload /absolute/path/photo.png
+```
+
+图片自动按 EXIF 方向旋转，居中 cover 裁剪到 320×172，透明区域按黑色合成。
+支持 sharp 能读取的静态图片；动画、固件、按键映射不在本工具范围。
+
+### 替换 Custom Animation 图片
+
+```sh
+npx --yes @yee94/qk80mk2 upload photo.png --target custom
+```
+
+`theme` = ABKT，`custom` = ABKG；不会自动切换键盘当前菜单。
+
+### 只编码，不访问键盘
+
+```sh
+npx --yes @yee94/qk80mk2 encode photo.png --out output/theme.abkt
+npx --yes @yee94/qk80mk2 upload output/theme.abkt
+```
+
+## 自动化
+
+```sh
+npx --yes @yee94/qk80mk2@0.1.0 upload /absolute/path/photo.png --json
+```
+
+stdout 为 JSON，进度写 stderr。失败退出码 1，SIGINT/SIGTERM 取消退出码 130。
+Ctrl+C 或传输异常会尽力发送 `0xE2` 取消并关闭串口，不会自动换 HID 或反复重试。
+
+成功结果例：
+
+```json
+{
+  "status": "sent",
+  "bytes": 110100,
+  "target": "ABKT",
+  "flowControl": false,
+  "packetDelayMs": 6,
+  "settleMs": 2000,
+  "displayVerified": false,
+  "port": "/dev/tty.usbmodem0000000000004"
+}
+```
+
+协议没有“屏幕渲染成功”确认，因此每次运行仍返回 `displayVerified:false`。
+实机验证记录与每次传输状态分开，不能用 `sent` 推断物理屏幕状态。
+定时调度请等上一次进程结束；建议分钟级而非每秒重复刷屏。
+
+### JS API
+
+```js
+import {encodeImage, upload, devices} from '@yee94/qk80mk2';
+
+console.log(await devices());
+const image = await encodeImage('/absolute/path/photo.png', {target:'theme'});
+const result = await upload(image, {
+  signal: AbortSignal.timeout(60_000),
+  onProgress: ({stage,sent,total}) => console.error(stage,sent,total),
+});
+console.log(result);
+```
+
+`upload()` 负责打开、传输、排空、等待和关闭。文件格式错误、设备错误、回包错误会抛异常。
+
+调试参数（保留默认值可复用已验证路径）：
+
+```sh
+node src/cli.js upload photo.png --packet-delay-ms 6 --settle-ms 2000 --timeout-ms 5000
+```
+
+## 与原 Python 实现的区别
+
+编码本身通过了官方比对；此前“主题不受支持”“HID 写入成功”的推断没有充分证据。
+
+| 原实现问题/不足 | 本项目处理 |
+| --- | --- |
+| 文件头仅检查错误字节，未验证完整回显 | 校验命令、回显和完整 64 字节包 |
+| HID 将 `0xFF` 回包视为成功，缺乏实际显示保证 | 不使用这条有争议的 fallback，固定 USB CDC |
+| 无逐包应答时连续写入 | 每个 64 字节包间隔 6 ms，接近 115200 baud / 8N1 的线速预算 |
+| 发送后立即关闭 | drain 后保持连接 2 秒，让设备处理尾部数据 |
+| `image uploaded` 容易被误解为显示成功 | 明确 `sent` 与实机显示验证的区别 |
+| 交互中断与异步串口事件处理不足 | 超时、取消、断连、分片/合并回包及排他锁 |
+
+限速和收尾等待这组设置已实机通过；尚未单独隔离哪一个因素导致旧版本 loading。
+不会将经验性延时描述为官网的隐藏指令，也不改写固件。
+
+## 测试与官方核验
+
+```sh
+npm test
+node scripts/verify-assets.js
+npm run verify:official -- /absolute/path/photo.png
+```
+
+测试覆盖流控开/关完整重组、文件头拒绝、回显损坏、用户取消、无效文件/参数、串口分片/合包、超时和断连。
+
+完整官方校验资源位于 `reference/official-assets/`，已纳入 Git 与 npm 包
+（开发校验资料，不是日常上传运行依赖）：
+
+- https://cfg.qwertykeys.com/assets/index-e0db734e.js → `index.js`
+- https://cfg.qwertykeys.com/tabkb/configs.json → `configs.json`
+- https://cfg.qwertykeys.com/assets/kbres-20adae5e.wasm → `kbres.wasm`
+
+WASM SHA-256：`20adae5e429f0aea9c788ea928756f9c3a884f9e2e581c70bc4dfbe345a8fd04`。
+校验程序先将输入规范化到 320×172，再运行同一份 PNG 的官方及本地编码。
+Node VM 仅用于执行可信的官方模块，不是安全沙箱。
+
+`reference/manifest.json` 记录来源、大小及 SHA-256。WASM 是 **6,810,636 字节的完整二进制**，
+不是 Git LFS 指针，也不会在安装时额外下载。
+
+## 项目结构
+
+```text
+src/
+  cli.js          命令行、JSON 输出、退出码
+  image.js        sharp 图像规范化、RGB565 与 ABKT/ABKG 编码
+  protocol.js     文件头握手、分包、应答与取消
+  serial.js       串口发现、读取缓冲、排他连接和资源释放
+  index.js        公共 ESM API
+scripts/
+  verify-official.js  运行官方 WASM，与本项目编码逐字节比对
+  verify-assets.js    检查随包资源 SHA-256
+reference/
+  official-assets/   完整官方 WASM / JS / 设备配置
+  manifest.json      资源清单
+  LICENSE.via-app    上游项目许可
+test/                串口协议与资源生命周期测试
+```
+
+## 常见问题
+
+- **找不到设备**：检查 USB 数据线与有线模式，运行 `qk80-screen devices`。蓝牙打字连接不等于 CDC 上传连接。
+- **串口被占用**：断开官网配置器及其他串口程序后再试，同一时刻只运行一个上传进程。
+- **文件头 `0xEE`**：设备拒绝当前文件；先核对型号、固件和编码，不要切换到未经确认的 HID fallback。
+- **loading**：传输期间短暂 loading 可能正常。默认限速和收尾等待已实机通过；如果持续卡住，保留报错和设备信息，不要循环盲传。
+- **图片不是当前页面**：`theme` 与 `custom` 是不同目标，此工具不会自动导航键盘菜单。
+- **自动化更新**：由外部程序生成图片，再调用 `upload` 替换；本项目只负责图片编码与设备传输。
+
+## 发布与许可
+
+```sh
+npm ci
+npm test
+node scripts/verify-assets.js
+npm pack --dry-run
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+发布包名固定为 `@yee94/qk80mk2`，项目 `.npmrc` 与 `publishConfig` 指向外网 npm。
+运行日志、个人数据快照及生成图片位于 `output/`，不提交、不打入 npm 包。
+原创代码使用 MIT；随附官方资源保留上游权利及许可说明，详见
+[LICENSE](LICENSE)、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,36 @@
+# Third-party material
+
+## Official Qwertykeys configurator snapshots
+
+`reference/official-assets/` contains unmodified resources downloaded from
+https://cfg.qwertykeys.com/ on 2026-10-18:
+
+| Local file | Upstream resource |
+| --- | --- |
+| `index.js` | `/assets/index-e0db734e.js` |
+| `configs.json` | `/tabkb/configs.json` |
+| `kbres.wasm` | `/assets/kbres-20adae5e.wasm` |
+
+These resources are bundled for reproducible, offline interoperability tests.
+They are not used during normal image encoding or USB upload. Copyright and
+third-party component notices inside these artifacts remain intact.
+Exact sizes and SHA-256 digests are recorded in `reference/manifest.json`.
+
+The deployed configurator links to https://github.com/tabkb/via-app as its source
+repository. That repository publishes a GPL-3.0 license, reproduced at
+`reference/LICENSE.via-app`. The deployment's exact source commit and the
+component-level license inventory of its compiled WASM have not been identified;
+the repository license is not asserted to be a complete WASM license inventory.
+No MIT relicensing of these third-party artifacts is intended.
+
+## Protocol reference
+
+The wire-format investigation was informed by
+https://github.com/Zephyr73/qk80mk2 (MIT) and the deployed official configurator.
+This project independently implements the static-image encoding and CDC uploader
+in JavaScript; it is not affiliated with Qwertykeys.
+
+## Runtime dependencies
+
+`serialport` and `sharp` are installed via npm; their own licenses and the licenses
+of their native/transitive dependencies apply. See their installed LICENSE files.

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@yee94/qk80mk2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "QK80 MK2 static theme uploader over USB CDC",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "yee.wang <wyy.xb@qq.com>",
+  "repository": { "type": "git", "url": "git+https://github.com/yee94/qk80mk2-node.git" },
+  "homepage": "https://github.com/yee94/qk80mk2-node#readme",
+  "bugs": { "url": "https://github.com/yee94/qk80mk2-node/issues" },
+  "keywords": ["qk80", "qk80mk2", "keyboard", "serialport", "lcd"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "files": ["src/", "scripts/", "reference/", "README.md", "LICENSE", "THIRD_PARTY_NOTICES.md", "CHANGELOG.md"],
+  "engines": { "node": ">=22" },
+  "bin": { "qk80-screen": "./src/cli.js" },
+  "exports": "./src/index.js",
+  "scripts": {
+    "test": "node --test",
+    "devices": "node src/cli.js devices",
+    "verify:official": "node scripts/verify-official.js reference/official-assets reference/official-assets/kbres.wasm",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": { "serialport": "^13.0.0", "sharp": "^0.34.0" }
+}