HolySister22/Toy-Android-App

# Toy Remote 一款免费、隐私的 Android 应用，用于控制蓝牙 (BLE) 玩具 —— 包含一个简洁的经典面板、一个有趣的“波浪”面板，以及**可选的**长距离远程控制功能。该功能可以通过您自行运行的 relay server，在两部手机之间进行控制。 无需账号。无跟踪。本地蓝牙控制完全离线工作。 ## 下载与安装 1. 前往 [**Releases**](../../releases) 页面并下载最新的 `toy-remote.apk`。 2. 在您的 Android 手机上，打开该文件并点击 **Install**。如果出现提示，请允许从未知来源 / 此浏览器安装。 3. 打开 **Toy Remote**，授予其请求的蓝牙（在 Android 9–11 上还包括位置）权限 —— 这是 Android 进行 BLE 扫描所必需的，且仅用于寻找您的玩具。 ## 功能特性 - **本地控制（仅限蓝牙）** —— 连接您的玩具并直接驱动它。 - **经典** 面板：每个电机一个滑块，外加一个“所有电机”总滑块。 - **波浪** 面板：为每个电机上下拖动滑块。 - **悬浮**：松开手指后，它会保持在当前水平。 - **序列**：通过拖动录制上下起伏的模式；松开手指后，它会无限循环播放。 - 通过将一个滑块停留在另一个滑块上方来组合电机；长按可拆分。 - **远程控制（可选）** —— 一部手机连接玩具（“共享”），另一部手机通过 relay server 从任何地方驱动它（“控制远程玩具”）。请参阅 [远程 / 自托管](#remote--self-hosting)。 - **安全第一。** 所有数值在到达硬件之前，都会在 Rust core 中被重新限制在玩具的安全上限内；如果 controller 断开连接或失去响应，gateway 会进入安全失效状态（将所有输出逐渐降为零）。 ## 远程 / 自托管 远程控制需要一台小型的、始终在线的 **relay server**，且两部手机都能访问它。该应用默认指向一个私有服务器，因此**开箱即用时，所有人都只能使用本地蓝牙控制** —— 远程控制属于“自带服务器”模式。 要为您自己启用远程控制： 1. 构建并运行 relay：`cd rust && cargo run --release -p toy-server`（监听 `0.0.0.0:8080`）。将其置于 TLS 之后，以便应用可以使用 `wss://your-host/ws`，或者通过诸如 [Tailscale](https://tailscale.com/) 的私有网络访问它。 2. 在应用中：**Settings → Signaling URL** → 您服务器的 `ws(s)://…/ws`。两部手机必须使用相同的 URL 并且能够访问它。 relay 仅在配对的两部手机之间转发不透明的消息；它完全不需要了解玩具本身。 ## 从源码构建 **Toolchain：** Flutter (stable)、Android SDK + NDK、JDK 17，以及配置了 Android targets 的 Rust toolchain (`rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android`)。 ``` cd app flutter pub get flutter build apk --release # signed if android/key.properties exists, else debug-signed ``` 输出的 APK 位于 `app/build/app/outputs/flutter-apk/app-release.apk`。 ### Release 签名 Release 构建使用 `app/android/key.properties`（已被 git 忽略）进行签名。要为您自己的构建签名，请创建一个 upload keystore 和该文件 —— 请参阅 [Flutter 签名指南](https://docs.flutter.dev/deployment/android#signing-the-app)。 如果没有此文件，项目仍然可以构建（退回到使用 debug 签名）。 ## 项目结构 ``` app/ Flutter app (UI + Bluetooth + relay client) lib/ Dart source rust/ Rust FFI crate (rust_lib_toy_remote) bridging Dart <-> core rust/ toy-core/ Toy-agnostic core: profile parsing, safety governor, encoding toy-net/ Transport abstraction (test harness) toy-server/ The relay / signaling server ``` **核心大脑**（配置文件、安全限制/渐变、命令编码、session 状态）使用 Rust 编写，并由应用和 server 共享；玩具被建模为通用的 *channels*，而不是某种特定的设备类型。 ## 许可证 本仓库中的代码基于 [MIT License](LICENSE) 发布。 注意：本应用使用 `flutter_blue_plus` 及其免费的 **非营利** 许可层级。这涵盖了免费的、非商业用途的使用；如果对该应用收费，则需要获取商业版的 `flutter_blue_plus` 许可证。

标签：Android, DSL, Rust, 可视化界面, 硬件控制, 移动应用, 网络流量审计, 蓝牙低功耗, 远程控制