简体中文 | English

通过本地推送,你可以让电脑上的应用或 AI Agent 经局域网直接连接 NOTE4,把日程、天气、照片或学习内容显示在墨水屏上,并用设备按键和麦克风与应用交互。

本页带你完成设备准备和第一次推图。开发接口以 公开 SDK 仓库 为准。

适用设备与版本

项目 要求
设备 ZECTRIX NOTE4,型号 zectrix-s3-epaper-4.2
画布 完整 400 × 300 像素
固件版本 NOTE4 固件 3.7.2 及以上版本均支持本地推送
网络 电脑与设备处于可互通的局域网
设备设置 在「设置 → 网络同步」中启用「待机保持 Wi-Fi」

内测说明:NOTE4 3.7.2 固件目前处于内测中。 如需参与内测,请加入我们的 QQ 群。

本指南不适用于 NOTE4C 四色开发板。NOTE4 固件 3.7.2 及以上版本均支持本地推送。请选择适用于自己设备型号的固件,不要混刷不同型号固件。

可以做什么

  • 推送画面:显示黑白、四灰阶或十六灰阶图片,适合信息看板、相册、课表和学习卡片。
  • 按键交互:接收上下键及确认键事件,由应用决定翻页、选择等行为。
  • 语音交互:接收设备按键触发的录音,或向设备播放音频。语音识别、语音合成与 AI 服务由应用自行接入。
  • 查询状态:读取电量、充电状态和 Wi-Fi 信号强度;具体能力以固件与 SDK 为准。

应用运行在电脑或其他兼容主机上,NOTE4 负责显示与交互。推送成功不代表应用已安装到设备;持续更新、按键和语音交互需要主机程序保持运行。

与云端推送有什么区别

方式 连接路径 参考文档
本地推送 本地程序通过局域网直接连接 NOTE4 本页及公开 SDK
云端 API 程序调用极趣云平台接口 云端 API 文档
小程序操作 使用「极趣空间」进行配网、图片推送等操作 小程序使用指南

本地设备通信无需经云端中转,也不要求先安装 Hub。应用若使用在线天气、AI 或其他网络服务,这些服务仍可能需要互联网、账号或 API 密钥。

第一步:准备设备

  1. 确认设备是 NOTE4,且固件为 3.7.2 及以上版本。
  2. 如需升级,用 Chrome 或 Edge 打开 极趣云,进入「本地升级」,使用 USB 数据线连接设备,按 官方固件说明 选择匹配固件。升级前保留重要配置与数据。
  3. 完成设备 Wi-Fi 配网,让电脑与 NOTE4 位于可互通的局域网。
  4. 在设备「设置 → 网络同步」中启用「待机保持 Wi-Fi」。保持联网会增加功耗,长时间使用请留意电量。
  5. 准备设备的局域网 IP 地址。可在路由器的已连接设备列表中确认;下面用 192.168.1.100 作为示例,实际操作必须替换。
  6. 退出正在连接同一设备的其他本地程序。同一时间仅由一个程序管理该设备。

第二步:选择应用或自行开发

使用社区应用

在 开发者社区 查看「本地应用」,按各项目说明安装或构建。不同项目的平台要求、依赖和接入方式可能不同;有源码不代表已有可直接安装的程序。

如果项目需要自行接入 SDK,按下文先验证最小推图流程,再加入应用逻辑。独立 SDK 不包含应用商店、插件加载器或桌面安装程序。

自行开发或交给 AI Agent

公开 SDK 提供 Rust 源码、图片/状态/按键/录音/播放示例和协议文档。先完成下面的一次推图,再扩展为天气看板、相册或交互式应用。

第三步:推送第一张图片

以下步骤面向使用源码的开发者。准备 Rust stable、平台 C/C++ 编译器和 CMake:macOS 使用 Xcode Command Line Tools;Windows 使用 Rust MSVC 与 Visual Studio C++ Build Tools;Linux 准备相应编译工具。SDK 仓库记录的验证平台为 Apple Silicon macOS,其他平台需自行构建验证。

git clone https://github.com/itopinion/zectrix-local-push-sdk.git
cd zectrix-local-push-sdk
cargo test --locked
cargo check --locked --examples

首次构建需要联网下载依赖。将一张 400 × 300 的 PNG 图片保存为仓库目录中的 card.png,然后执行:

cargo run --locked --example show -- 192.168.1.100 card.png mono

将 IP 替换成自己的设备地址。mono 为黑白,改为 gray4 或 gray16 可尝试四灰阶或十六灰阶。建议先用黑白图片确认连通,再观察灰阶效果。

SDK 会处理图片转换和传输。请提供原始 PNG,避免应用先抖色、SDK 再抖色;JPEG 或 SVG 需由应用先转换为 PNG。

如何判断成功: show() 成功代表设备已报告显示完成,而不只是发送完成。仍应观察实机画面,确认文字大小、排版和灰阶效果;系统通知可能临时覆盖部分画面。

如需查询设备状态,可单独运行:

cargo run --locked --example status -- 192.168.1.100

上述是独立示例,逐个运行;不要同时启动多个示例争用同一设备。若构建时出现旧版 Opus 的 CMake 兼容性错误,可按 SDK README 设置 CMAKE_POLICY_VERSION_MINIMUM=3.5 后重试。

按键、录音与退出

应用可以接收上下键短按/长按、确认键短按,并自行定义这些按键的作用。连接后的交互不应直接套用普通时钟页或待办页的操作说明。

配套固件中,长按确认键达到录音阈值后会显示「正在聆听 / 松开结束」,提示音结束后开始录音,松开结束。SDK 没有远程开启麦克风的接口。收到录音不等于已经识别成文字,应用需要自行接入识别能力。

完整 400 × 300 画布都可用于应用,不需要永久预留顶部区域。系统的录音提示和待办通知会临时覆盖,结束后恢复应用画面。

关闭或切换应用时,让原程序先断开设备;开发者正常退出时调用 close()。连接中断后,应用需要明确建立新连接,SDK 不会在后台自动重新接管设备。

常见问题

现象 建议检查
找不到设备或连接超时 确认设备联网、待机保持 Wi-Fi 已启用、IP 正确;检查访客网络隔离及防火墙是否阻止本地通信。
提示 Busy 先检查是否有其他程序占用设备;当前录音、播放或图片任务也可能造成忙碌,等待当前操作结束后再判断。
连接时提示协议或色板不兼容 确认 NOTE4 固件为 3.7.2 及以上版本,再按 SDK 文档和错误信息检查所用接口。
图片比例不对或文字太小 按 400 × 300 设计画面,优先使用清晰的大字号;其他尺寸会按比例缩放并居中。
电脑休眠或程序退出后不再更新 持续更新依赖主机应用运行与网络连接,恢复主机后重新连接。
结果为 ResultUnknown 操作可能已经执行,但无法确认;先检查设备,程序不要自动当成新请求重复刷图或播放。
接收到了音频却没有文字或 AI 回答 SDK 只负责音频传输;识别、TTS 和模型需由应用配置。

交给 AI Agent 的开发需求

把下面这段话和你的具体应用需求一起交给 AI 编程助手:

请基于 https://github.com/itopinion/zectrix-local-push-sdk 开发一个 NOTE4 本地应用。先阅读最新 README 和 docs/API.md,核对我的设备型号并确认固件为 3.7.2 及以上版本;不要自动升级固件。使用我指定的设备地址,不连接其他设备。生成 400×300 PNG,先实现单张黑白图推送,再增加业务功能。保持一个设备连接,持续消费按键与录音事件,正常退出时调用 close。不要把传输完成当成显示完成,不要把 ResultUnknown 自动作为新请求重发。先完成本机构建和测试,再根据设备显示完成回执报告结果,并说明尚未实机验证的部分。

开发资料

本页更新于 2026-11-02。本地推送支持 NOTE4 固件 3.7.2 及以上版本;具体接口用法与变化请查阅 SDK 文档。