已发布项目

cwo-trainer-3a66769c

Revision 1

Initial draft

CWO 莫尔斯电码训练器 · 使用说明

一台拿在手上的莫尔斯电码（CW）练习机：敲点划、屏幕实时解出字母数字、耳机/扬声器同步发声。不需要联网，不需要连电脑，上电就能用。

快速上手

  1. 上电，等屏幕出现界面（约 2 秒）

  2. 左键 = 点 ·，右键 = 划 —，按下去就发声

  3. 试试敲出 H 和 E：

    ····（四下左键）→ 停顿一下 → ·（一下左键）→ 停顿

    停顿之后屏幕上应该出现 HE

  4. 想调速度/音量/屏幕方向 → 两个键一起按住约半秒，进入设置

屏幕说明

              ┌──────────────────────┐
              │ CWO TRAINER   WPM 20 VOL 40 R 270 │  ① 状态栏
              ├──────────────────────┤
              │                      │
              │        ·—··          │  ② 符号区：你正在敲的点划
              │                      │
              ├──────────────────────┤
              │ HELLO WORLD          │  ③ 解码区：解出来的字符
              │                      │
              ├──────────────────────┤
              │ WPM       20  (15-30)│  ④ 设置区（只在设置模式显示）
              │ L/R = -/+  HOLD = ...│  ⑤ 提示栏：当前能按什么
              └──────────────────────┘
位置 内容
① 状态栏 当前速度 WPM、音量 VOL、屏幕方向 R（0/90/180/270）
② 符号区 当前这一个字符已经敲进去的点划，字很大，解出来后会清空
③ 解码区 解出来的字母和数字，满屏会自动清空重新开始
④ 设置区 只在设置模式出现，显示参数名和当前值
⑤ 提示栏 随模式变化，告诉你这时按键是什么作用

界面图

两张图由 GSP 模拟器按设备的 ui/main.json 渲染，和机器上是同一套渲染管线（图中的点划与文字是示例内容）。

普通模式 —— 符号区是你正在敲的点划，解码区是已经解出来的字符：

image

设置模式 —— 双键同按进入后，底部出现参数名和当前值，提示栏变成设置操作说明：

image

按键总览

普通模式（平时发报）

按键 作用
左键 短按 点 ·（按下即发声）
右键 短按 划 —（按下即发声）
双键 同时按住 0.4 秒 进入设置模式

设置模式（调参数）

按键 作用
左键 短按 当前参数 −1 步
右键 短按 当前参数 +1 步
左键 长按 0.6 秒 切到上一个参数
右键 长按 0.6 秒 切到下一个参数
双键 同时按住 0.4 秒 退出设置模式

参数顺序循环：WPM → VOLUME → ROTATION → 回到 WPM

每按一次加减都会立刻用新值响一声，不用看屏幕也能听出变化。

按键映射

设备上只有两个物理按键（都在交互子板上），所有功能都由这两个键的短按 / 长按 / 双键同按组合而成。

物理键 手势 普通模式 设置模式
左键 短按（< 0.6 秒） 输入点 · 当前参数 −1
左键 长按（≥ 0.6 秒） 无 切到上一个参数
右键 短按（< 0.6 秒） 输入划 — 当前参数 +1
右键 长按（≥ 0.6 秒） 无 切到下一个参数
左右双键 同时按住 ≥ 0.4 秒 进入设置模式 退出设置模式

映射的判定细节：

项目 取值 说明
按键来源 交互子板 GPIO 直读 不走触摸通道；上电后子板枚举约需 3 秒才可响应
轮询周期 10 毫秒 按键状态每 10ms 采样一次
消抖 连续 3 次采样一致（约 30ms） 机械抖动不会产生假按键
双键同按 两键都稳定按下并持续 ≥ 400ms 只是碰巧同时按下不算，必须按住
长按 设置模式下按住 ≥ 600ms 普通模式没有长按功能
生效时机 普通模式：按下瞬间
设置模式短按：松手时		 普通模式按下即发声，判定长按不会给发报带来延迟

屏幕方向不影响按键功能。 ROTATION 只旋转显示内容，左键永远是「点 / −」、右键永远是「划 / +」。把机器转个方向拿，键的功能不会跟着变 —— 需要的是把画面转到对着你。

进入设置那一次的双键同按不会留下字符。 和弦按下的瞬间在普通模式下会先喂进去 · 和 —（连起来是 A），进入设置时会被撤销。

三项可调参数

参数 含义 范围 每步 出厂默认
WPM 发报速度（每分钟多少词） 15 – 30 1 15
VOLUME 音量，0 为静音 0 – 100 10 50
ROTATION 屏幕方向（顺时针角度） 0 / 90 / 180 / 270 90 0
  • WPM 越大越快：速度会同时改变你听到的点划长短和机器判定字符结束的快慢。练熟了再往上加。
  • ROTATION 改完立刻生效，屏幕当场转过来，不用重启。
  • 三项都会自动保存，断电再上电仍然是上次的设定。

解码是怎么判的

机器靠「你停顿多久」来判断一个字有没有敲完：

你输入的 机器怎么理解
点 按住时间 1 个单位
划 按住时间 3 个单位
敲完一个字，停顿约 4 个单位 这个字符结束了，开始解码
再继续停顿到 8 个单位 补一个空格，表示一个词结束

单位长短由 WPM 决定，比如 WPM 20 时一个单位是 60 毫秒，也就是：

  • 点 = 60ms，划 = 180ms
  • 字内停顿 240ms 以上 → 这个字解出来
  • 停顿 480ms 以上 → 再加一个空格

支持 A–Z 和 0–9。 敲出表里没有的组合会显示 ?。

常见问题

Q：屏幕上一直显示 ? 怎么办？ 你能敲的点划组合不在莫尔斯表里，通常是敲多了或敲错了。不用管它，接着敲下一个字就行。一个字符最多 20 个点划，超了也会判成 ?。

Q：数字总是解不出来 / 解成两个字母？ 数字（0–9）都是 5 个点划，必须一口气敲完、中途别停顿。如果手速跟不上，把 WPM 调低，判定窗口会变长，就容易了。

Q：敲错了想删掉一个字怎么办？ 目前没有退格功能，只能继续往下敲。解码区攒满 64 个字符（4 行 × 16 个）后会自动清空，重新开始。

Q：屏幕上刚敲的东西突然不见了？ 这是设计如此 —— 解码区满了 64 个字符会自动清空，否则新字符会超出屏幕看不见。

Q：没声音？ 先看状态栏的 VOL：

  • 如果是 0，进设置按几下右键加音量
  • 如果音量正常还是没声音，检查扬声器/耳机有没有插好

Q：屏幕方向是歪的 / 我想横过来用？ 进设置，长按切到 ROTATION，短按左右键转到你要的方向（0/90/180/270），屏幕会立刻转过来。

Q：双键一起按了但没进设置？ 需要同时按住满 0.4 秒。快速连打左一下右一下（两键重叠时间很短）不会被当成同按，那是正常的连打。

Q：按键完全没反应？ 确认手柄式的交互子板插稳了。开机后模块枚举需要约 3 秒，刚上电的一两秒内按键可能不响应，稍等一下再试。

Q：设置会掉电丢失吗？ 不会，速度/音量/方向都自动保存，每次开机自动载入。

练习小贴士

  • 先按默认 WPM 15 敲熟常用字母：E ·、T —、A ·—、N —·、S ···、O ———
  • 想练听音抄报，可以把 WPM 往上调（20、25…），判定窗口会同步收紧
  • 练习「词」的时候，敲完一个字停一下、敲完一个词停久一点，屏幕上就会出现空格
  • 进入设置那一次的「双键同按」不会在解码区留下多余字符，可以放心用

固件升级

CWO 通过 ESP-Iris 的 System Update 升级：新固件写入独立的应用分区，不会清掉你保存的 WPM / 音量 / 方向，升级完屏幕状态栏显示的还是上次的参数。

需要准备

  • 一台装了 ESP-Mosaico 开发环境的电脑（ESP-IDF + mosaico.py）
  • 一根 USB 数据线，能出现串口即可

升级步骤

  1. 用 USB 线把设备连到电脑

  2. 在 workspace 根目录（esp-mosaico-vibe/）打开终端，设置环境变量：

    $env:IDF_TOOLS_PATH = "E:\TREA_WORKSPACE\espressif-tools"
$env:IDF_PATH       = "E:\TREA_WORKSPACE\esp-idf"

  3. 编译 + 打包 + 写入并激活：

    python submodule\esp-mosaico-utils\mosaico-tools\mosaico.py iris system-update --project projects/cwo --timeout 1800

  4. 命令会先编译（几分钟），然后把设备切到 Recovery 写入新固件，最后自动切回应用

  5. 设备重启后屏幕重新出现界面即完成

每个 mosaico.py 命令都必须在 workspace 根目录下执行，否则会报 No .mosaico.json was found。 已经编好包、只想重新写一遍时，在上面命令后面加 --skip-build 跳过编译。

确认版本

python submodule\esp-mosaico-utils\mosaico-tools\mosaico.py iris list --project projects/cwo

看输出里的 app_version。版本号定义在 projects/cwo/CMakeLists.txt 的 project(cwo VERSION x.y.z)。

升级失败怎么办

现象 处理
USB devices are reserved ... state=owned 上一次会话还占着设备，先执行 iris reconcile --device-id <ID> --project projects/cwo 再重试
卡在 waiting_recovery 后报 outcome_unknown 固件通常已经写进去了。reconcile 之后加 --skip-build 再跑一次即可
设备从电脑上"消失"（串口不见了） 拔掉 USB 再插上，等设备重新枚举，然后 reconcile + 重试
设备完全起不来（反复重启 / 停在 Recovery 画面） 见下节「抢救」

抢救：设备起不来

recover 会把设备恢复到基础固件（Recovery 镜像），用于抢救无法启动的设备。它是顶层命令，不在 iris 下面：

# 设备无响应时先进入下载模式：按住 BOOT 键，插入 USB，再松开 BOOT
python submodule\esp-mosaico-utils\mosaico-tools\mosaico.py recover --timeout 1800

恢复完成后设备停在 Recovery，再跑一次第 3 步的 system-update 把应用写回去。

抢救性恢复后如果发现参数变回了默认值（WPM 15 / VOL 50 / R 0），重新设置一次即可 —— 这种情况只可能出现在 recover 之后，正常升级不受影响。