liufumingren aecb85d55b feat(android): 新增「启动时切到模拟输出」开关与输出路由诊断
个别 Allwinner 机型(T95MAX / Android 12)三种输出 AUDIO_CODEC / AUDIO_SPDIF /
AUDIO_HDMI,只有 CODEC(AV/3.5mm)有声音,但每次插着 HDMI 开机都会被重置成 HDMI。

实测结论(已写进 README):
- HAL 只在初始化时读 vendor.audio.output.active;运行期
  AudioManager.setParameters(raw_data_output / mediasw.sft.rawdata /
  audio_output_channel / devices_out_active / routing)与 setPreferredDevice 全被忽略;
- 只有「设属性 + 重启 vendor.audio-hal」才切到 open card=0(需 root,App 没有 su)。

因此新增开关仅作“尽量尝试 + 打印当前输出”:
- AudioOutput.applyCodec() 用反射调 AudioManager.setParameters 下发厂商参数,
  并在不支持时打日志「音频输出切换未生效 当前仍是 XXX」便于现场排查;
- 开关默认关闭(多数机型本来就走模拟输出,不需要动它)。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-16 17:38:21 +08:00

250 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# AndroidStation(设备端)
面向 Android TV / 电视盒子的**扫码设备端**:把 USB 扫码枪的结果通过局域网推给桌面端
(`desktop/` 的扫码服务),并且在 UDP 48899 上扮演网口扫码设备,让桌面端自动发现。
原「扫描中心(AndroidScanCenter)」的中控业务已整体删除:不再扫描别的设备、不再管理通道、
不再有手势登录 / 网络设置 / 条码 HTTP 上报。
## 技术栈
- 语言 / UI:**Java + XML 布局**(不使用 Kotlin、不使用 Compose)
- 包名:`com.gztbyc.scancenter`(沿用原工程,便于现场覆盖安装)
- minSdk 21 / targetSdk 28 / compileSdk 35
- Gradle 8.11.1 + AGP 8.7.3,JDK 17
- 依赖:仅 `androidx.appcompat`(纯 Java,无 native 库 → 与 CPU 架构无关)
## 工作方式
```
桌面端(desktop/Services/Scan) AndroidStation
│ UDP 48899 广播 {"Type":"EP_Tool",...} → DiscoveryResponder
│ ← 自己的 {"MAC","HostName","Type",...} (同一个 socket 回复)
│
│ TCP 8087 主动连接 → ScanServer(服务端)
│ ← 扫码结果(UTF-8 + CRLF) USB 扫码枪(键盘 HID)
```
- **允许被发现**:`DiscoveryResponder` 绑定 UDP 48899,收到发现广播就按设备固件的字段回复
(协议见 [`docs/udp-48899-protocol.md`](docs/udp-48899-protocol.md))。
- **扫码上报**:`ScanServer` 监听 TCP 8087,桌面端连上后,主界面收到的每一条扫码结果
都会按行推送过去。桌面端下发的扫码枪串口设置指令会被读取并丢弃(本机是 USB HID)。
- **下游播报(面单摄像头)**:桌面端识别到条码后,只给型号是 `AndroidStation`(安卓扫描通道)的通道
在同一 TCP 连接上下发 `0x1E + {"cmd":"scan","id":"…","code":"…"} + "\n"` 控制帧;本机**先蜂鸣一声**(方波 2.7kHz/90ms,
和语音拼在同一段 PCM 里一次播出来)**再播报后四位 + 开始打包**,并在主界面显示这条条码,
然后**回执** `0x1E + {"cmd":"ack","id":"…"} + "\n"`(id 必须原样回显;桌面端据此确认通知成功,超时会重发)。
播报/显示都不会把条码回推给桌面端(避免回路)。
网口扫码枪没有语音能力,桌面端不给它们发;但**扫码记录与通知无关**,安卓端离线也照样落库上传。
- **兼容桌面端添加通道**:响应 JCMD `10001 / 10003 / 10005 / 10017`,报出一条
`packcenter / TCP-SERVER / 8087` 的 SOCK 条目;桌面端写 `SYS.HostName` 会更新设备名,
写 `SOCK.LocalPort` 会改本地服务端口。`20003` 只确认,不重启本机。
- **不改 IP**:网络参数只读上报,设置页没有改 IP / 掩码 / 网关的入口。
## 主界面
- 设备名称 / MAC / IP / 型号版本 / 服务与发现状态 / 累计扫码(面单摄像头下发的会单独计「面单 N」)。
- 最近 8 条扫码记录(**每 5 秒才刷新一次**,不参与扫码热路径);
桌面端下发的面单条码会**立刻**刷新界面,并带 `[面单]` 前缀,最近条码下面写「面单摄像头识别:时间」,
现场据此确认「摄像头认的是不是这张面单」(只显示、只播报,不回推桌面端)。
- USB 扫码枪是键盘设备:在 Activity 层统一收键,连续可打印字符攒成一条条码,
回车/Tab 立即提交;没有后缀时停手 **50ms** 自动提交。
- ⚠️ **结束键不一定是回车**:实测 Newtologic DW-8200(T95MAX / Android 12)发的是
`KEYCODE_DPAD_CENTER`(code 23)。所以「结束键」判定要包含 DPAD_CENTER,并且**只认
发过条码字符的那台设备**(比较 `event.getDeviceId()`)——否则遥控器的 OK 键会被误当成
结束键,而枪的 DPAD_CENTER 又会落到当前焦点按钮上(现场表现:一扫就进「服务设置」,
焦点在「清空记录」时还会把记录清掉)。
- 底部「服务设置」「清空记录」两个按钮可用遥控器操作。
- `FLAG_KEEP_SCREEN_ON` 保证长期不接显示器时 Activity 仍保持前台、服务不被挂起。
### 扫码性能约定(重要)
设备长期不接显示器,扫码路径必须尽量短:
```
按键 → 追加缓冲 → 提交 → StationService 入队 → 后台写线程 → 桌面端
```
#### 语音播报「开头被吞」的处理(踩过的坑)
实测这段临时 WAV 起播时开头会被吃掉一小段(起播延迟 + 音频输出通道切换),
表现是「后四位」里第一个/前两个数字、或者**蜂鸣声**听不到。所以:
- PCM 最前面垫静音 `LEAD_IN_MS = 300`,尾部垫 120ms(避免还没播完就被 `release`);
- **蜂鸣必须排在静音之后**(`300ms 静音 → 嘀 160ms → 40ms → 后四位`):
只垫 60ms 就让蜂鸣起播时,蜂鸣正好落在起播损耗窗口里,经常整个被吞;
- **先 `start()` 新的 MediaPlayer,再停/收掉上一句**:反过来会让音频输出通道在起播瞬间被拆,
开头更容易被吞;
- `setVolume(1f, 1f)` 兜一下某些 ROM 的淡入。
- **按键/扫码回调里不同步刷新任何 UI、不写日志**;界面由 1 秒的时钟和 5 秒一次的状态刷新兜底。
- socket 写入只在 `station-scan-write` 单线程里做,避免主线程 `NetworkOnMainThreadException`,
同时保证多条扫码按顺序发出。
- **不做任何去重**:同一个条码连续扫到多少次就上报多少次,重复帧由桌面端自己判断。
- 条码校验只做首尾非字母数字清理 + 4~64 位长度检查,不用正则。
## 语音播报(离线)
设备没有显示器,扫码后要能听到「后四位 + 开始打包」。
- 设备上只有 `PicoTts` 且**没有中文语音数据**,所以运行时**不用 TextToSpeech**。
- 用 `tools/fetch-voice-seeds.ps1` 从现场语音服务(`http://tbdata.gztbyc.com/voice/<文本>`)
一次性抓取 `0-9`、`A-Z`、`开始打包`,统一转成 **44.1kHz / 立体声 / 16-bit PCM**,
放到 `app/src/main/res/raw/voice_*.wav`;运行时只读本地资源,**断网也能播报**。
- 播放用系统 `MediaPlayer` 读临时拼接的 WAV(这台 rk3288 的 `AudioTrack` 初始化会失败),
在 `station-speech` 独立线程完成,不阻塞扫码上报。
- 同一串条码 2.5 秒内不重复播报(连续扫描的重复帧);换了条码立即打断上一句播最新的。
- **输出路由(踩过的坑)**:个别 Allwinner 机型(实测 T95MAX / Android 12)有三种输出
`AUDIO_CODEC / AUDIO_SPDIF / AUDIO_HDMI`,只有 CODEC(AV/3.5mm)有声音,而**每次插着 HDMI
开机都会被重置成 `AUDIO_HDMI`**(属性 `vendor.audio.output.active`)。
该 HAL 只在**初始化时**读这个属性:运行期 `AudioManager.setParameters`
(`raw_data_output` / `mediasw.sft.rawdata` / `audio_output_channel` / `devices_out_active` / `routing`)
和 `MediaPlayer/AudioTrack.setPreferredDevice` **全部被忽略**;只有「设属性 + 重启
`vendor.audio-hal`」才会切到 `open card=0`(需要 root,普通应用没有 su)。
所以这一层只能靠现场:系统设置里选一次 CODEC(会丢)、HDMI 音频分离器、音箱接电视、
或换机型。应用侧保留「启动时把音频输出切到模拟输出」开关(默认关)与当前输出日志,
在支持该参数的机型上有效,在这类机器上只会打印「切换未生效」便于排查。
**上报不受影响**:重复条码仍然逐条发送。
- 语音内容:条码末尾 4 个字母/数字(标点跳过)+ 「开始打包」。
- 启动时 `BarcodeSpeaker.maximizeVolume` 把媒体音量设为最大(实测 `11 -> 15`)。
需要 `MODIFY_AUDIO_SETTINGS` 普通权限。
- 重新生成种子:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\fetch-voice-seeds.ps1 -Force
```
脚本依赖 `desktop/native/ffmpeg/ffmpeg.exe`;生成的 WAV 需要一起提交。
## 服务设置
只保留服务参数:
| 项 | 默认值 | 说明 |
| --- | --- | --- |
| 设备名称 | `Build.MODEL` / `工位终端` | 广播里的 `HostName`,桌面端用它显示通道名 |
| 扫码服务端口(TCP) | **8087** | 桌面端连上来读扫码结果 |
| 设备发现端口(UDP) | **48899** | 桌面端发现广播的目标端口 |
| 启用扫码服务 | 开 | 关掉后不监听 TCP |
| 允许被桌面端发现 | 开 | 关掉后不应答 UDP 广播 |
⚠️ 修改端口后要和桌面端约定保持一致(桌面端常量见
`desktop/Services/Scan/ScanChannel.cs` 的 `ScanProtocol`)。
## 常用命令
所有构建/装机/抓日志统一走 `tools/android.ps1`(`.vscode/tasks.json` 只做转发),
脚本内会自动探测 JDK 与 adb:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\android.ps1 dev
```
任务:`build` / `install` / `run` / `dev` / `logs` / `clean` / `devices`;
选项:`-Variant` / `-Serial` / `-CleanFirst` / `-NoLaunch` / `-NoLogcat`。
直接用 Gradle 也可以(需自行设置 `JAVA_HOME`,本机 `java` 不在 PATH):
```powershell
$env:JAVA_HOME='C:\Users\lfmingren\AppData\Local\Programs\EclipseAdoptium\jdk-17.0.20.1+1'
.\gradlew.bat :app:assembleDebug
```
APK 产物:`app\build\outputs\apk\debug\app-debug.apk`
## 正式包(签名 + 发布)
release 包用仓库根目录 `keystore/packservice-release.jks` 签名,密码放在 `keystore.properties`
(两者都被 `.gitignore` 忽略,**发布机必须自行备份**;丢了就只能换包名重新发)。
```powershell
# 只构建正式包(产物 app\build\outputs\apk\release\app-release.apk)
$env:JAVA_HOME='C:\Users\lfmingren\AppData\Local\Programs\EclipseAdoptium\jdk-17.0.20.1+1'
.\gradlew.bat :app:assembleRelease -PversionName=1.0.1 -PversionCode=10001
```
发布(构建 + 上传到服务器 `download/android_client/`)统一走后端脚手架,配置和桌面端同套路:
```powershell
cd ..\backend
npm run android:build # 只构建(dry-run),产物在 backend\android_client\out
npm run android:publish # 构建 + 上传 + 刷新 nginx
```
下载地址 `https://<域名>/download/android_client/YuncangScan-<版本>.apk`
(版本信息 `.../android_client/version.json`)。
## 日志
- 统一用 `com.gztbyc.scancenter.util.L`(静态导入后 `log(...)` / `i(...)` / `w(...)` / `e(...)`),
**不要直接写 `android.util.Log`**。
- tag 固定为 `AndroidStation`,类名+方法名+行号自动附在消息里;单条超 3000 字符自动分段。
- release 包默认不输出,需 `adb shell setprop log.tag.AndroidStation DEBUG` 才打开。
- **新增代码必须保留日志链路可用**:不要删掉 `buildFeatures { buildConfig true }`,
`L` 依赖 `BuildConfig.DEBUG`。
## 安装与开机启动
- 这是**普通用户应用**:只需要 `INTERNET`、`RECEIVE_BOOT_COMPLETED`、
`MODIFY_AUDIO_SETTINGS` 三个普通权限,`/data` 直接安装即可。
- 不依赖 Device Owner / 设备管理员 / lock task / 系统应用(kiosk 方式见下文,也是纯普通应用)。
- `BootReceiver` 监听 `BOOT_COMPLETED`,开机后自动拉起 `MainActivity`。
开机后还会用 `AlarmManager` 在 **6 秒 / 15 秒**各补一次「切回前台」(`FLAG_ACTIVITY_REORDER_TO_FRONT`)。
⚠️ Android 的既定行为:**新装后必须手动启动一次**,应用才脱离 stopped 状态,
之后重启才会收到开机广播。
- ⚠️ **电视盒子 ROM 会拦后台启动 Activity**:实测 G96max H616(Android 10)即使 targetSdk=28,
开机广播拉起界面也会被拒(`logcat` 里 `Background activity start … isBgStartWhitelisted: false`),
结果是服务起来了、界面被盒子自带桌面 `com.swe.dgbluancher` 顶到后台。
这种机器要**把它设成盒子桌面(kiosk)**,由系统自己启动:
```bash
# 设成桌面(开机直接进扫码界面,不会再被桌面抢前台)
adb shell cmd package set-home-activity com.gztbyc.scancenter/.MainActivity
# 校验:isDefault=true / com.gztbyc.scancenter/.MainActivity
adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME
# 想还原成盒子自带桌面
adb shell cmd package set-home-activity com.swe.dgbluancher/.MainActivity
# 设成桌面后要进系统设置:adb shell am start -a android.settings.SETTINGS
```
普通手机/平板(不设 HOME)只靠 `BOOT_COMPLETED` 就够。
- 主界面不在后台驻留额外服务;扫码服务随应用进程生命周期运行。
## 服务设置
设备名、扫码服务端口(TCP)、发现端口(UDP)、两个启停开关,以及 **「开机 / 桌面」** 一栏:
- **设为默认桌面**:调用 `RoleManager.createRequestRoleIntent(ROLE_HOME)`,由**系统自己**弹
「要将扫码终端设为您的默认主屏幕应用吗?」的确认框(`取消` / `设为默认应用`)。
不需要 adb、不需要 root,也**不用先把默认桌面清掉**;
- **解除默认桌面**:**Android 不允许应用自己放弃 HOME 角色**(只有系统/设备管理员能 `removeRoleHolder`),
所以点它弹一个框,给三条路:
1. 打开系统「主屏幕应用」页 → 选回盒子自带桌面(个别 ROM 这页一开就闪退,见下);
2. **卸载本应用**(`ACTION_DELETE` 系统卸载确认框)→ 桌面角色自动释放,盒子回自带桌面,需要时再装;
3. 取消(改用下面的「回到盒子桌面」);
- **回到盒子桌面**:不改默认设置,直接把机器上**另一个**桌面应用拉到前台(临时用一下);
- **打开系统设置**:设成桌面后现场唯一的系统入口;
- 状态行会显示当前是「扫码终端」还是「盒子自带桌面」,按钮按状态自动置灰。
⚠️ 已知 ROM 缺陷:**G96max H616(Android 10)的系统「主屏幕应用 / 默认应用」页会闪退**
(`java.lang.NullPointerException: android.app.ActionBar.setDisplayHomeAsUpEnabled … null object reference`),
只有 `com.android.tv.settings` 的「设置」首页能开。这种机器上解除桌面只能走
**卸载本应用**,或者用 adb:
```bash
adb shell cmd package set-home-activity com.swe.dgbluancher/.MainActivity # 还原成盒子自带桌面
```
为什么要设桌面:部分电视盒子 ROM 禁止应用在后台拉起界面
(`logcat`:`Background activity start … isBgStartWhitelisted: false`),开机广播收到也切不到前台。
Android 10 以下没有 RoleManager 时,这一栏会提示去「设置 → 应用 → 默认应用 → 主屏幕应用」手动选择。
- 依赖仓库走阿里云镜像,Gradle 分发走腾讯云镜像,改动仓库配置时保持国内源优先。
- 主界面以遥控器为主:可点击控件必须方向键可达,并在 `res/drawable/bg_button.xml`
这类 selector 中提供 `state_focused` 视觉反馈。
- 界面文案统一放 `res/values/strings.xml`,不硬编码在 XML / Java 中。
- **不要再加「跳系统设置页面」的入口**:这台盒子的 Settings 清单里声明了一些页面,
但厂商把它们从 dex 里删掉了,用组件名启动会让系统设置当场崩。
- **不要再把中控逻辑搬回来**(设备扫描 / 通道管理 / 回放 / 手势 / 网络设置 / HTTP 上报)。
本工程只负责「当一台扫码设备」。