From fd45537bd5fd8870ed771a0d172aecc7040c3a25 Mon Sep 17 00:00:00 2001 From: Cytrogen Date: Fri, 20 Mar 2026 12:24:53 -0400 Subject: [PATCH] Replace README.md with Chinese README.org Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 69 --------------------------- README.org | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 69 deletions(-) delete mode 100644 README.md create mode 100644 README.org diff --git a/README.md b/README.md deleted file mode 100644 index 72298e4e14b47a34caca3b5a5f511e08db97d4a0..0000000000000000000000000000000000000000 --- a/README.md +++ /dev/null @@ -1,69 +0,0 @@ -# VBHelper - -Application to interact with the Vital series, VB, VH, VBC and VBBE. - -## Current state of the project - -Right now the project is still under development, and until further notice, any database updates will result in having to erase application data. - -This document will be updated once the application does not need any more database resets. - -## Features - -As of now, the project allows you to read characters, view characters stats, and send them back to your watch. - -You can also apply items to the characters read, such as special missions, or change timers, and store characters in the storage section. - -You also earn new items every time an item such as a special mission (VB only) or a character completes an in-app adventure mission. - -App also comes with a dex that will update every time a new character is added, and allows you to see evolution requirements and current adventure stage in the watch. - -## How to set up - -1. Download the latest version for VB Arena APK from a trustworthy source. If your download is a standalone APK, continue to step 2. Otherwise, if your download is an XAPK, do the following: - - 1. Using your phone file manager, rename the XAPK file to ZIP, and extract its contents. You can also do this with any other device, such as Windows, macOS and Linux. - - 2. Once the files are extracted, look for an APK called `com.bandai.vitalbraceletarena.apk`. Copy it somewhere else, you will need it. - -2. Install an APK release for VB Arena. You will find the releases [here](http://github.com/nacabaro/vbhelper/releases). Download the latest release and install its APK. - - Note, in the current stage of the project, you will have to delete the old application from your device. If the app keeps crashing after installing, clear application data and storage. - -3. Import secrets in the app. These secrets will allow the app to talk to the watch. On the main screen, click on the gear icon, then `Import secrets`. - - You will be prompted to choose a file. Choose the APK file that was previously obtained. - -4. Import cards. Due to copyright laws, we cannot offer the characters and sprites themselves in the application. In order to import the cards do the following. - - 1. Using your own DiM/BEm cards, dump the cards to your device. You can get an in-depth tutorial in [here](http://mrblinky.net/digimon/vb/dimcardtool/dimcardtool.html). You can download the dump tool from [here](http://mrblinky.net/digimon/vb/dimcardtool/) - - 2. Once installed the tool and drivers, open the tool, connect your DiM/BEm reader hardware to yout computer and click on Read card. - - 3. Transfer the resulting file to your mobile device. You can put them anywhere, as long as they are accessible. My recommendation is to put them under a folder called `Cards` in your `Internal storage` or `SD Card` - - 4. In the app, click on import card. Next choose the BIN file corresponding to the card you want to import. - - **Note: if you do not import the card, whenever you attempt to read a character from th watch, the character you read will get deleted.** - -5. App will now be ready to be used. - -## Planned features - -- Online battles, undegoing development by `lightheel`. - -- VitalWear compatibility, undergoing development by `cfogrady`. - -- Support for multiple languages, not yet started. - -- Database backup/restore. - -## Credits - -- `cyanic` for helping us understand more about the VB connection protocol. - -- `cfogrady` for making both [`VB-DIM-Reader`](https://github.com/cfogrady/VB-DIM-Reader) and [`lib-vb-nfc`](https://github.com/cfogrady/lib-vb-nfc) - -- `lightheel` for working on the online component in the application, both server and battle client. - -- `shvstrz` for the app icon. \ No newline at end of file diff --git a/README.org b/README.org new file mode 100644 index 0000000000000000000000000000000000000000..363a05ae60918f5e6db8f36aacc91b45d52dada2 --- /dev/null +++ b/README.org @@ -0,0 +1,134 @@ +#+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