packServer/AndroidStation
liufumingren 7a82bf13c7 revert(android): 移除无效的「启动时切到模拟输出」开关
实测该 Allwinner HAL 只在初始化时读 vendor.audio.output.active,运行期
AudioManager.setParameters 与 setPreferredDevice 全被忽略,开关不起作用,
去掉避免误导;排查结论保留在 AndroidStation/README.md。

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

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)。
  • 扫码上报: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。该 HAL 只在初始化时读 vendor.audio.output.active:运行期 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 -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 -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):

$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 忽略,发布机必须自行备份;丢了就只能换包名重新发)。

# 只构建正式包(产物 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/)统一走后端脚手架,配置和桌面端同套路:

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),由系统自己启动:

    # 设成桌面(开机直接进扫码界面,不会再被桌面抢前台)
    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:

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 上报)。 本工程只负责「当一台扫码设备」。