KEYE 帮助中心
设备 帮助
KeyeSmartCup 设备放在桌面上的产品示意图
帮助文档

使用说明

这个页面把设备首次联网、设备 PIN 登录、服务端播放列表编辑、设备设置和每个 widget 的使用说明放在同一个文档里，方便你在不离开帮助页的情况下完成设置和排障。

打开设备页

快速开始

新设备第一次使用时，目标是先完成“连接 Wi-Fi -> 查看设备 PIN -> 登录设备控制台”这条闭环。

  1. 给设备上电，单击进入 AP 配网页。
  2. 用手机或电脑连接 KeyeSmartCup，密码是 password。
  3. 在浏览器打开 http://192.168.4.1，填写要连接的 Wi-Fi 信息。
  4. 联网成功后，设备配网页会显示设备 PIN、设备 ID / MAC 和当前固件版本。
  5. 在浏览器打开 http://penholder.keye.ai/device，输入 9 位设备 PIN 登录设备控制台。

设置成功时你会看到什么

  • Wi-Fi 配置成功：设备配网页能显示设备 PIN，且不再停留在反复重连状态。
  • 设备登录成功：打开 http://penholder.keye.ai/device 后，不再停在 PIN 登录页，而是进入 Playlist 和 Device Settings 页面。
  • 播放列表保存成功：你刚刚调整的页面顺序、持续时间和参数会在控制台里立即保留下来。
  • 内容开始生效：顶部预览会先更新；墨水屏会在下一轮请求或刷新时切到新的页面内容。

播放列表上手

对这台设备来说，播放列表就是“它接下来要轮流显示哪些页面”的清单。设备不会只显示一个固定页面，而是按播放列表的顺序，一页接一页地向服务端取内容并显示在墨水屏上。

你可以把每一个播放项理解成一张页面卡片：它包含页面类型、这个页面要显示多久、以及这个页面自己的参数。设备登录后最重要的工作，就是先把这个列表配对。

播放列表的作用是什么

  • 决定显示顺序：第 1 项先显示，第 2 项后显示，后面的页面继续轮播。
  • 决定显示内容：每一项的 widget_id 对应一种页面类型，例如时钟、天气、股票、邮件或订阅页面。
  • 决定停留时长：每一项的 duration_seconds 决定该页面在设备上持续多久。
  • 决定页面细节：每一项自己的 params 决定城市、股票代码、邮箱、订阅 PIN 等具体内容。

新用户应该如何设置

  1. 先添加 2 到 3 个最基础的页面，例如 Clock、Weather、Calendar。
  2. 先确认全局设备设置已经填好，特别是 timezone、location 和需要时的 display_variant。
  3. 再回到 Playlist，从左侧选择 widget 加入右侧列表。
  4. 按你希望的播放顺序拖动排序，把最常看的页面放前面。
  5. 给每个页面设置持续时间，再根据 widget 类型填写自己的参数。
  6. 点击保存后，再用单项 Preview 或顶部 3D 预览确认结果。

最重要的参数

  • duration_seconds：这是最重要的播放参数。它决定页面会停留多久。控制台里显示为 Duration，按分钟编辑，保存时会转换成秒。
  • widget_id：决定页面类型。选错 widget，就算参数填对了，显示的也不是你想要的页面。
  • position：决定顺序。你不需要手填，拖动排序后系统会自动同步。
  • params：决定页面细节。例如天气需要位置、股票需要代码、订阅页面需要 publisher_pin。

关于页面持续时间

如果一个页面停留时间太短，用户还没看完就切走；太长，又会让整台设备看起来很久都不更新。对于新用户，建议先从每页 1 到 5 分钟开始，再根据页面类型慢慢调整。

  • 时钟、天气、日历这类基础信息，通常可以设置得稍长一些。
  • 股票、邮件、订阅内容这类更容易变化的信息，可以设置得相对短一些。
  • 如果播放列表页面很多，每一页时间又很长，整轮轮播周期会非常久，这是最常见的“为什么感觉设备不更新”的原因之一。

常见操作

  • 添加 widget：左侧卡片区点击 widget，或把 widget 拖到右侧播放列表里。
  • 拖动排序：已经加入播放列表的卡片可以上下拖动，保存后设备会按新的顺序播放。
  • 拖出删除：把播放列表里的卡片拖出列表区域，会把这项从当前设备的 playlist 中移除。
  • 单项预览：每个播放项都有 Preview 按钮，用来触发服务端生成该 widget 的实时预览。
  • 参数隔离：每个卡片自己的参数都保存在该播放项里，不会自动覆盖别的 widget。

日常使用

联网后，设备会从服务端请求播放内容。你在控制台里看到的预览，是设备内容的编辑和查看入口。

  • 播放内容管理：在 http://penholder.keye.ai/device 添加或调整 playlist 项目，服务端按设备 PIN 决定当前页面。
  • 设备设置：可在 Device Settings 中维护时区、位置和显示变体等资料。
  • 预览与实机差异：控制台顶部 3D 预览用于快速确认内容，但墨水屏实际刷新不会像 LCD 一样即时。
  • 设备 PIN：用于登录和分享设备身份；它不是 Wi-Fi 密码，也不是管理后台账号。

已保存内容后，设备通常会在下一轮渲染或刷新时更新。如果网络请求失败，设备会回退到本地模拟时钟。

播放设置与设备设置

当前控制台把“设备级共享设置”和“单个播放项参数”分开保存。前者在 Device Settings 中维护，后者留在 Playlist 卡片内部。

设备级共享设置

  • timezone：全局时区。时钟、日历、天气、股票、世界时钟等 widget 默认会读取这里。
  • location：全局位置。天气 widget 没填自己的位置时，会回退到这里。
  • calendar_source：日程来源 URL。服务端渲染 agenda 类内容时可以复用这项。
  • profile_name：设备资料名。适合放设备昵称，也可被部分 widget 当作展示名使用。
  • display_variant：显示变体。当前用于决定预览图和渲染变体，例如 landscape_400x300。

播放项自己的设置

  • 每个播放项至少包含 widget_id、duration_seconds、position、enabled 和 params。
  • position 不需要手工维护，拖动排序后系统会自动同步。
  • params 是 widget 自己的输入，例如股票代码、订阅设备 PIN、邮箱 IMAP 信息或世界时钟城市列表。
  • 保存 Device Settings 不会覆盖已有 Playlist；保存 Playlist 也不会改掉全局时区和位置。

每个 Widget 的使用说明

下列说明以当前设备控制台和服务端公开的 widget 为准。优先写“什么时候用、至少要填什么、有哪些特殊点”。

Agenda

用来显示个人日程。至少需要 timezone；如果要接真实日历，可以额外提供 CalDAV 相关参数，或配合设备级 calendar_source 使用。适合展示当天事件列表。

Calendar

用来显示月份视图。常用参数是 timezone 和可选的 date；如果不填，默认按当前日期所在月份展示。

Crypto

用来跟踪加密货币列表。常用参数是 ids 和 vs_currency，例如 bitcoin,ethereum,solana 配合 usd。如果不填，自带默认主流币列表。

Flip Clock

这是翻页时钟样式。至少需要 timezone，可选 hour_mode 为 12 或 24，也可以通过 invert_colors 切换浅深反相效果。

用来显示 GitHub 热门仓库。正常使用时只要能访问服务端数据源即可；做静态预览时可以手动填写仓库名、作者、描述、语言和 star 数。

Stock

用来显示股票行情。常用参数是 symbol 和 market，例如 AAPL / NASDAQ。不填时会回退到默认股票。

Subscription Feed

这个 widget 用来引用别的发布源。常用参数是 publisher_pin，即另一台发布设备的 9 位 PIN。当前控制台也支持 feed mode 切换，用来自用或订阅其他设备内容。

Clock

最基础的时钟卡片，只要求 timezone。如果你只想确认设备联网、渲染链路和刷新链路正常，优先用它做基线测试。

生字轮播

用来按年级和册次轮播生字。常用参数是 grade 和 term；服务端会为每个设备 PIN 单独记录当前推进到的字，并在页面上显示当前汉字、拼音和所属分组。

Email

用来显示未读邮件数。常用参数包括 provider、email、app_password、imap_host、imap_port 和 mailbox。这些 IMAP 凭证目前保存在当前播放项中，不要填普通登录密码，Gmail 和 iCloud 都应使用应用专用密码。

Weather

用来显示天气。最常用的是 location 和 timezone；如果播放项里没单独填位置，会回退到设备级 location。适合放在第一个或第二个页面做日常状态查看。

Word

用来做单词学习。它依赖 device_pin 记录每台设备自己的学习进度，所以同一个词库在不同设备上可以独立推进。显示名可结合全局 profile_name 使用。

World Clock

用来显示多城市时间。常用参数是 cities，格式为 城市名|时区，多项用逗号分隔；例如 Shanghai|Asia/Shanghai,London|Europe/London。适合跨时区会议或海外团队。

Token Quota

用来显示模型或服务的额度。至少涉及 provider、quota_url 和 token；控制台会按当前 provider 生成或更新相应凭证，再由服务端抓取剩余额度。适合监控 Codex、Claude、Gemini 一类服务的剩余配额。

常见问题

下面这些问题覆盖了当前最常见的设备上手与排障场景。

连不上 Wi-Fi，怎么办？

先确认你连接的是设备自己的 AP：KeyeSmartCup。如果配网页能打开但保存后仍失败，优先检查 Wi-Fi 名称和密码是否正确，确认目标网络可用，并重新进入配网页再保存一次。

设备已经联网，但控制台里看起来像离线或不更新？

先确认控制台保存成功，再观察设备是否进入下一轮刷新。当前设备不是实时双向面板，服务端内容修改后通常要等到下一次请求或刷新才会在屏幕上体现。

为什么设备 PIN 登录失败？

设备控制台要求输入 9 位设备 PIN。请以设备配网页或设备说明里显示的 PIN 为准，字母大小写不敏感，但输入的字符必须完整。

为什么保存了内容，屏幕却没有立刻变化？

这是当前产品流程的正常现象之一。控制台预览更快，墨水屏刷新较慢，而且设备按自己的刷新节奏取下一张内容。先确认控制台保存成功，再等待下一轮刷新。

墨水屏残影、闪屏、刷新慢，是不是故障？

不一定。墨水屏和普通屏幕不同，刷新时可能闪屏，也可能出现短暂残影；这类现象常常是正常的显示特性。只有在多次刷新后内容仍长期不变化，才更像需要排查的异常。

补充说明

  • 墨水屏适合低频更新的信息展示，不适合持续高帧率交互。
  • 如果需要人工支持，优先提供：设备 PIN、当前 Wi-Fi 状态、是否能打开 http://penholder.keye.ai/device、以及保存后设备是否有下一轮刷新。