v0.3.1 · 限频亮屏与省电优化

Codex Passport 0.3.1 减少连续提醒造成的长时间亮屏，并在熄屏后停止普通界面重绘。同步、未读记录、大 dashboard 和三会话进展页继续保留。

• 新的待回复／待批准通知最多每 5 分钟自动亮屏一次，每次约 15 秒。连续提醒不续亮，开机历史、重复投递和冷却期内的提醒不会稍后补亮。
• 新安装默认 35% 亮度、30 秒无操作后熄屏。已有亮度、熄屏、静音和配对设置保留；按键查看仍使用保存的时长。静音只控制声音，不关闭视觉提醒。
• 熄屏后继续接收数据和确认回执，唤醒前更新画面；降低主循环空闲轮询和电量读取频率。首次按键只唤醒，上／下切页的规则保持。
• Android 补充通知亮屏说明，并更新「日常使用」预设。Python 0.3.1 更新版本信息和指南，0.3.0 中继与现有手机 App 仍兼容新版固件。
• USB 增加只读 POWER 诊断，可检查实际背光占空比和重绘次数，不输出会话或网络凭据。

升级：省电策略需要更新 Passport 固件。APK 可覆盖安装，签名与 0.3.0 一致；无需卸载或重新配对。Python 可按指南升级并保留状态目录。APK 仍使用调试签名。

codex-passport-0.3.1.bin 是应用固件，只写入官方设备布局的 0x10000，保留 bootloader、分区表、NVS、cardid 和 Recovery。不要整片擦除，也不要把这个应用文件写到 0x0。下载文件附 SHA256 校验和第三方许可证。

验证：33 项 Python 测试（源码及隔离 wheel 环境）、原生省电／提醒／按键回归和固件／APK 构建通过。行为相同的开发固件实测连续提醒后 15.401 秒熄屏、两次自动亮屏间隔 304.088 秒；熄屏继续同步且不重绘。手机与电脑 BLE 往返及主动查找通过，用户确认首次 OK 只唤醒、未读保留、两页切换正常。正式 0.3.1 固件已通过写入校验及手机路径的版本回执。

未测量实际省电比例或续航；本轮未复测 Wi-Fi、首次配对码、RF 距离和外网 WireGuard。手机新版说明页完成构建，实机链路验收使用现有 App。当前仍为只读进展伴侣，回复、恢复会话和审批在 Codex 中完成。

English: Version 0.3.1 bounds attention-triggered wakeups to about 15 seconds, no more than once every five minutes, and defers normal rendering while dark. Saved settings, unread state and BLE bonds remain intact. Android updates presets/guidance; the Python update contains metadata and documentation changes. Existing 0.3.0 relay/app installations remain compatible. The wake policy and physical buttons passed the checks described above; battery savings have not been measured. Flash only the application binary at 0x10000 on the documented official layout. The APK is debug-signed with the same certificate as 0.3.0.

中文一步步入门 · Python / uvx · 省电检查 · 验证记录

Codex Passport 0.3.0

Codex Passport 0.3.0 adds quieter reminders, phone-guided setup, device preferences and optional Wi-Fi synchronization. Threads are ordered by their latest actual interaction, so background tools and reconnects no longer move old conversations to the top.

• Only new input/approval requests qualify for a short chime, at least two minutes apart. Double OK toggles mute without clearing unread notifications. Ordinary results update silently.
• Android now includes guided connection checks and a Device page for sound, brightness, timeout and finding Passport. Settings are confirmed by physical device receipts and retained after restart.
• Optional 2.4 GHz Wi-Fi connects Passport directly to a trusted private IPv4 HTTP relay. Provision from the paired phone; failed synchronization returns to phone BLE. Existing Wi-Fi settings can be reused or forgotten.
• The large dashboard and three-thread progress page remain. User messages, visible replies and explicit input/approval requests drive thread order.
• codex-passport setup shows the computer address and pairing details, then starts the relay. The beginner guide covers installation, device updates, onboarding, Wi-Fi, quiet settings and troubleshooting.

Update Python, Android and firmware together. Keep the relay state directory and device pairing storage. The APK is debug-signed. Write only the app binary at 0x10000 on the documented ESP32-C3 AI Passport layout; retain bootloader, partition table, NVS, cardid and Recovery.

Validation: 33 Python tests, isolated wheel installation, native protocol/control/alert/pace tests, real Android onboarding/settings, Wi-Fi reboot and failure recovery, and device receipts across Wi-Fi/computer BLE/phone BLE transitions. The user verified double OK retains unread notifications. Final device pages were visually checked with synthetic captures.

Battery endurance, RF range and off-LAN WireGuard were not tested. Conversation replies, session resume and approvals remain in Codex; this is a read-only companion.

中文一步步入门 · Python 安装 / uvx · 验证记录

v0.2.0 · Dashboard and session progress

The original large Passport dashboard stays. A second page adds compact quota visualization and the three most recently updated visible Codex sessions, each with a title, current state and short progress summary.

Device controls

• Short UP/DOWN: switch between the two pages.
• Hold UP/DOWN: switch quota windows on either page.
• Short OK while awake: mark notifications read.
• Hold OK: reconnect BLE and keep pairing bonds.
• First press while asleep: wake only.

Progress is read-only: no detail menus, conversation continuation, replies or approval actions. New alerts wake the screen without changing the selected page. Starts update silently; old completion summaries are not shown as progress for a newly started turn.

The device now receives up to three bounded titles and summaries over encrypted BLE. A bundled 16 px OFL CJK font supports spaces and basic Chinese/Japanese characters; unsupported emoji/rare glyphs are omitted rather than displayed as missing-glyph boxes. The phone retains its separate notification inbox.

Upgrade

Update Python relay, Android APK and Passport firmware together to 0.2.0. Keep the relay state directory and phone settings. Flash only the Passport application at 0x10000 on the documented hardware layout; preserve bootloader, partitions, NVS, cardid and Recovery. APK is debug-signed.

uvx --index https://pypi.org/simple --from 'codex-passport-sync==0.2.0' codex-passport --help

For persistent hooks use the source environment or uv tool install --index https://pypi.org/simple 'codex-passport-sync[ble]==0.2.0'. Restart the relay and reopen existing Codex sessions after updating hooks.

• 一步步入门指南
• Python package
• Two real-device synthetic previews
• Validation record

Validation: 22 Python tests, native button checks, strict firmware and Android builds, physical rendering of both pages, user-verified page/window switching and wake-only behavior, and four computer/phone BLE transitions with matching device receipts. Source and unpacked release artifacts passed private-data scans. Off-LAN WireGuard and battery endurance remain unmeasured.

v0.1.1 · PyPI and beginner setup guide

Python packaging and beginner documentation update. The Android app and Passport firmware remain at v0.1.0; no device reinstall or reflash is required for this update.

Install the Python package

uvx --from 'codex-passport-sync==0.1.1' codex-passport --help

For persistent hooks and computer BLE, use uv tool install 'codex-passport-sync[ble]==0.1.1' or the source-environment setup in the beginner guide. Do not bind long-lived hooks to a temporary uvx cache.

• PyPI package
• 中文：从零开始的逐步指南
• Python / uvx installation options
• Android APK and Passport firmware v0.1.0

The guide covers tools, private Flash backup, app-only flashing, APK installation without ADB, relay IP/token configuration, pairing, a real notification test, physical buttons, login startup, BLE handoff, troubleshooting, updates and removal.

Validation: 20 tests pass against the installed wheel; strict package metadata checks, uvx launch, isolated persistent installation and hook installation pass. Markdown local links and all 35 shell blocks were checked; Codex account RPC initialization was verified. Source and unpacked distributions were scanned for private data, including the actual publishing and relay credentials.

This release does not add conversation continuation, replies or approval controls. Off-LAN WireGuard and battery endurance remain unmeasured; see the validation record.

If a configured mirror has not synchronized the new package, add --index https://pypi.org/simple to the uvx or uv tool install command. Official PyPI installation was verified; no global mirror changes are needed.

v0.1.0 · Notifications and usage

Codex Passport v0.1.0 provides meaningful Codex session notifications and quota visualization on FoloToy AI Passport, with a Material 3 Expressive Android companion.

• Computer BLE direct delivery or Android forwarding over a private LAN/VPN.
• One active BLE owner, phone fallback, durable delivery receipts and offline replay.
• Quota remaining versus time remaining, with visual pace indicators.
• Native Passport button controls and a graphical 240×320 dashboard.

This version displays notifications and bounded summaries. It does not provide conversation continuation, replies, approvals, or other human-in-the-loop controls.

See the repository's validation record for measured results. Off-LAN WireGuard was excluded from this release's acceptance and has not been physically tested; battery endurance has not been measured.

The APK uses a debug signature. Firmware must be written only to the factory app partition at 0x10000 on the documented hardware layout, preserving bootloader, partitions, NVS, cardid and Recovery. See the README before flashing.

Python wheel example:

uvx --from ./codex_passport_sync-0.1.0-py3-none-any.whl codex-passport --help

Direct BLE requires the optional ble dependencies. Source installation: uv sync --extra ble.

Setup guide and Python update

Start with the step-by-step Chinese guide. Python 0.1.1 is now available on PyPI and works with this release's APK and firmware. No device reflash is needed for that documentation/packaging update.