AndroidStation - 有的扫码枪(Newtologic DW-8200,T95MAX/Android 12)用 KEYCODE_DPAD_CENTER 当结束键, 之前只认 ENTER/TAB:结束键会落到当前焦点按钮上(一扫就进「服务设置」,焦点在 「清空记录」时还会清空记录),而且扫码只能等 50ms 超时才提交。现在按 deviceId 认 “刚发过条码字符的那台设备”,DPAD_CENTER 也算结束键,遥控器 OK 键不受影响。 - 新增「播报走本机扬声器(AV / 3.5mm)」开关(默认关):个别机型插 HDMI 时 HAL 会把 媒体声音锁在 HDMI 声卡,需要显式指定内建扬声器。 桌面端 - 发现列表改为按 MAC 就地合并,不再整表 Clear(每 3 秒一次刷新会把 ListView 的选中项 和滚动位置清掉,现场表现为“设备选不中”)。 - 「添加为通道」从标题行移到列表行内「操作」列,不再依赖选中项。 后端 - NVR 唯一键由全局 (host, port, username) 改为 (subject_id, host, port, username): 不同仓库的内网地址经常相同,之前会报「已被其他主体添加」。查重也只查本主体。 - 新增迁移 20261116010000-scope-nvr-unique-to-subject 与按主体范围的测试。 构建 - android_client/build.ps1:gradle 把 javac 的 stderr 提示写出来时,PowerShell 的 $ErrorActionPreference='Stop' 会把它当终止错误,release 包必失败;改为只以退出码判定。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
240 lines
14 KiB
Markdown
240 lines
14 KiB
Markdown
# 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 秒内不重复播报(连续扫描的重复帧);换了条码立即打断上一句播最新的。
|
||
**上报不受影响**:重复条码仍然逐条发送。
|
||
- 语音内容:条码末尾 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 上报)。
|
||
本工程只负责「当一台扫码设备」。
|