#+TITLE: VBHelper
#+AUTHOR: cytrogen
#+DESCRIPTION: Vital Bracelet 系列设备的 Android 辅助应用

* 简介

VBHelper 是一个用于与 Vital Bracelet 系列设备（VB、VH、VBC、VBBE）交互的 Android 应用。通过 NFC 读取/写入角色数据，管理卡片，追踪冒险任务，并处理与设备通信所需的加密密钥。

#+begin_quote
项目仍在积极开发中。在进一步通知之前，数据库更新可能需要清除应用数据。
#+end_quote

* 功能

** 核心功能
- 通过 NFC 读取角色数据并查看角色属性
- 将角色写回手表
- 对角色使用道具（特殊任务、计时器等）
- 角色仓库管理
- 冒险任务系统——完成任务可获得新道具
- 图鉴系统——读取新角色时自动更新，可查看进化条件和当前冒险阶段
- 数据库导入/导出

** 推送通知（新功能）
基于 [[https://unifiedpush.org][UnifiedPush]] 协议的推送通知系统，在计时器到期时通知用户：

- 冒险任务完成提醒
- 角色进化倒计时提醒
- 特殊任务到期提醒
- BE 训练计时提醒
- BE 道具效果到期提醒

需要自部署推送服务器（项目包含 Ktor 服务端）和 UnifiedPush 分发器（如 [[https://ntfy.sh][ntfy]]）。

* 使用方法

** 1. 获取 VB Arena APK

从可信来源下载最新版 VB Arena APK。如果下载的是 XAPK 格式：

1. 将 XAPK 重命名为 ZIP 并解压
2. 找到 =com.bandai.vitalbraceletarena.apk= 文件并保存备用

** 2. 安装 VBHelper

从 [[http://github.com/nacabaro/vbhelper/releases][Releases]] 下载最新的 APK 并安装。

#+begin_quote
在当前开发阶段，更新时可能需要先卸载旧版本。如果安装后闪退，请清除应用数据和存储。
#+end_quote

** 3. 导入密钥

密钥用于与手表通信。在主界面点击齿轮图标，然后选择「Import secrets」，选择之前获取的 VB Arena APK 文件。

** 4. 导入卡片

由于版权限制，应用不包含角色和素材数据。你需要使用自己的 DiM/BEm 卡片：

1. 使用 [[http://mrblinky.net/digimon/vb/dimcardtool/][DiM Card Tool]] 将卡片数据导出到电脑
2. 将导出的文件传输到手机
3. 在应用中点击「Import card」，选择对应的 BIN 文件

#+begin_warning
如果未导入对应卡片就读取手表中的角色，该角色数据将被删除。
#+end_warning

** 5. 设置推送通知（可选）

*** 部署推送服务器

项目包含一个 Ktor 服务端，用于调度计时器和发送推送通知。

*Docker 部署（推荐）：*

#+begin_src bash
cd server
docker compose up -d
#+end_src

*手动运行：*

#+begin_src bash
JAVA_HOME=/path/to/jdk17 ./gradlew :server:buildFatJar
java -jar server/build/libs/server-all.jar
#+end_src

服务器默认监听 =0.0.0.0:8080= 。

*** 配置应用

1. 在手机上安装 UnifiedPush 分发器（如 [[https://ntfy.sh][ntfy]]）
2. 打开 VBHelper → 设置 → Notifications
3. 设置推送服务器地址（如 =http://your-server:8080= ）
4. 启用推送通知
5. 使用「Test Notification」验证配置

* 构建

** 前置条件
- JDK 17
- Android SDK（compileSdk 36）
- =vb-nfc-reader= 0.2.0-SNAPSHOT 和 =vb-dim-reader= 2.1.0 需安装到 mavenLocal

** 构建应用
#+begin_src bash
JAVA_HOME=/path/to/jdk17 ./gradlew :app:assembleDebug
#+end_src

** 构建服务端
#+begin_src bash
JAVA_HOME=/path/to/jdk17 ./gradlew :server:buildFatJar
#+end_src

* 计划功能

- 在线对战——由 =lightheel= 开发中
- VitalWear 兼容——由 =cfogrady= 开发中
- 多语言支持——尚未开始
- 数据库备份/恢复

* 致谢

- [[https://github.com/nacabaro][nacabaro]] — 项目原作者
- =cyanic= — 帮助理解 VB 通信协议
- [[https://github.com/cfogrady][cfogrady]] — 开发了 [[https://github.com/cfogrady/VB-DIM-Reader][VB-DIM-Reader]] 和 [[https://github.com/cfogrady/lib-vb-nfc][lib-vb-nfc]]
- =lightheel= — 开发在线对战组件（服务端和客户端）
- =shvstrz= — 应用图标设计

* 许可证

本项目基于 [[file:LICENSE][MIT 许可证]] 开源。

Copyright (c) 2026 cytrogen