AndroidStation(原中控改造为纯设备端) - 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报 - 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报 - 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满 - 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」 - 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启) - 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖 发布脚手架 - backend/android_client:Android 正式包构建(build.ps1 + package.config.json) - backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish - 桌面端安装包改为 download/desktop,Android 为 download/android_client; version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json - 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」 - git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
17 KiB
UDP 48899 设备发现协议(ScanHome / 庆科 High-Flying)
来源:设备商工具
E:\BaiduNetdiskDownload\ScanHome网口配置\IOTService分析方式:实测抓包 + 反查运行配置 + 提取 jar 内字符串常量。 标注 [实测] 的是抓到的原始数据,[代码] 来自 jar 常量,[推断] 需真机复验。
1. 结论摘要
局域网设备发现走 UDP 广播:工具向 255.255.255.255:48899 发一段 JSON,
设备回包给发送方,工具据此得到设备 MAC / IP / 型号等信息,随后切到设备的管理端口做配置。
- 报文是纯文本 JSON,
PasswordEn=0时不加密(见 §5)。 - 广播间隔约 3 秒,设备 30 秒无响应判掉线。
- 广播里的
ConnectMode决定是否顺带改写设备的服务器地址——配置端必须用Forbidden。
2. 端口分配
来自 IOTService\IOTService\res\ep_tool.properties [代码]:
| 配置项 | 值 | 含义 |
|---|---|---|
UDP_BROADCAST_PORT |
48899 | 广播目标端口(设备在此监听) |
UDP_LOCAL_PORT |
48897 | 工具本地端口 |
JCMDUDP_PORT |
48896 | JCMD 协议 UDP 端口 |
JCMDTCP_PORT_START/END |
48898 / 49898 | JCMD 协议 TCP 端口段 |
VPATH_UDP_PORT |
28987 | 虚拟串口 UDP |
VPATH_TCP_PORT_START/END |
28990 / 29990 | 虚拟串口 TCP 端口段 |
VTH_SERVER_PORT |
28986 | — |
SCAN_INTERVAL |
2999 ms | 广播间隔 [代码] |
DEVICE_TIMEOUT |
30000 ms | 掉线判定 |
IOT_HEARTBEAT_INTERVAL |
30 | 心跳 |
ZONE |
EPort |
区域标识,出现在报文里 |
另实测到设备的管理端口是 UDP 5555(见 §4)。
3. 广播请求报文 [实测]
抓到的原始包(161 字节,UTF-8,无换行):
{"Agent":0,"Type":"EP_Tool","PasswordEn":0,"ServPort":0,"Version":"3.1.3f",
"ConnectMode":"Forbidden","Zone":"EPort","ServEn":1,"ServAddr":"0.0.0.0","ClientEn":0}
字段含义(对照 iotservice/device/jcmd/JcmdBroadcast.pack() [代码]):
| 字段 | 类型 | 说明 |
|---|---|---|
Agent |
int | 代理号,0 = 本机直连 |
Type |
String | 报文类型,固定 EP_Tool |
Version |
String | 工具版本,实测 3.1.3f(取 iotservice/IOTService.version) |
PasswordEn |
int | 是否启用密码/加密,0 = 明文 |
Zone |
String | 区域,EPort |
ConnectMode |
String | 是否改写设备服务器配置,Forbidden = 只发现不修改 |
ServEn |
int | 是否让设备启用「主动连接服务器」 |
ServAddr |
String | 让设备连接的服务器地址,0.0.0.0 表示不改 |
ServPort |
int | 同上,端口 0 表示不改 |
ClientEn |
int | 是否启用客户端模式 |
DevMac |
String | 定向查询时才有:指定 MAC 只查该设备(广播时省略) |
注意抓包里没有 DevMac,因为它只在定向查询时出现——JcmdBroadcast 里该字段是按需 put 的。
4. 交互时序
日志 IOTService\IOTService\log.txt 第 15–31 行 [实测]:
15: VcomManager started...
16: Start to Scan...
17: ***VcomDriver recv len:55 ← 设备心跳
19: VCOM recv heartBeat!
20: ***VcomDriver recv len:62 ← 设备发现回复(62 字节)
22: ..VCOM recv add! ← 识别为新设备
23-28: (另外两台设备,同样 62 字节)
29: Device ACCF23EA6D8C is on!192.168.10.83:48899
30: vcomudp channel connected!
31: Send:10-Bytes,To:192.168.10.83/5555 ← 切到设备管理端口
所以完整流程是:
- PC 广播 JSON →
255.255.255.255:48899(多网卡时每个广播地址各发一次) - 设备回一段明文 JSON 给发送方(实测 188~189 字节,见 §6)
- PC 与设备建立
vcomudp通道做后续配置
日志里的
***VcomDriver recv len:62/len:55是另一条链路(vcom 心跳)的长度, 不是广播回复;广播回复实测是 188~189 字节,不要混。
两个关键行为 [实测]
- 回复发往「广播的源地址 + 源端口」。工具发送用的是临时端口(实测 53278),
不是
UDP_LOCAL_PORT=48897。 → 在 48899 上 bind 收不到回复,必须自己发广播并在同一个 socket 上收。 - 一次广播可能收到多个回复:实测发 10 次探测收到 20 个包。
因为同时发往
255.255.255.255与子网广播192.168.11.255, 同一块网卡上的设备两个包都收得到,于是各回一次。 → 实现时必须按 MAC 去重,不能按“收到几个包”算设备数。 - 设备回复的源端口是 48899(即设备从自己的 48899 发出)。
5. 加密
util/AESCrypt.class [代码]:
- 硬编码密钥(16 字符 = AES-128):
`&hFiotseRViCe$' - 算法:
AES/CBC/NoPadding,IV 取密钥自身 HFEncrypt(byte[])=padding()+EncryptCBC();HFDecrypt(byte[])=DecryptCBC()+unPadding()- 提供
byteToHexString/hexStringToByte一组十六进制辅助方法
但实测广播报文是明文。 结合 PasswordEn=0 与配置里没有任何密码项,可以判断:
未设密码时收发都不加密,AES 只在设了密码的场景启用(HFEncrypt 内部对空密钥做了短路)。
这意味着接入时不需要实现 AES——先按明文做,等遇到设了密码的设备再补。 若将来要支持加密,注意
NoPadding+ 自定义 padding 需要逐字节对齐还原。
6. 设备回复报文 [实测]
实测抓到一台真实设备(192.168.9.208,与探测机同在 192.168.11.56/22 网段),
188~189 字节,明文 JSON:
{"Agent":0,"Type":"E10C","Version":"1.41.1","ClientEn":1,"HostName":"8号",
"CustomerID":"E10C","Uptime":"0-Day 0:8:44\r\n","Zone":"EPort",
"UdpSupport":1,"MAC":"402A8FBB15D8","State":"Idle"}
| 字段 | 示例值 | 说明 |
|---|---|---|
Agent |
0 |
代理号 |
Type |
E10C |
设备型号(非固定值,这里是 E10C) |
Version |
1.41.1 |
设备固件版本 |
ClientEn |
1 |
客户端模式开关 |
HostName |
8号 |
设备名,UTF-8 编码(用 GBK 解会乱码) |
CustomerID |
E10C |
客户/型号标识 |
Uptime |
0-Day 0:8:44\r\n |
运行时长,字符串尾部带转义的 \r\n,解析时要 trim |
Zone |
EPort |
区域,与请求一致 |
UdpSupport |
1 |
是否支持 UDP 配置 |
MAC |
402A8FBB15D8 |
设备唯一标识,12 位十六进制无分隔 |
State |
Idle |
设备状态 |
字段名对照
JcmdBroadcast.parse(JSONObject, Device) 还会读
Status / productID / uartStatus / uartSetup / swVer / Local / position——
但这些不在广播回复里,应该是定向查询(带 DevMac)或连上之后才返回。
与云端 bridge 协议的字段名不同,两套不要混:
| 含义 | 局域网广播回复 | 云端 bridge |
|---|---|---|
| MAC | MAC |
DevMac |
| 型号 | Type / CustomerID |
ModuleType |
| 版本 | Version |
Version |
| 在线 | State |
Online |
| 设备名 | HostName |
HostName |
设备型号实测到
E10C;云端日志里出现过的型号:E10/E20/E30/EP10/EP20/HF2211/HF5111A/HF5111B/HF2221/HF5142A/HF5142B/HF5182/HF5111/HF2111/HF2411/HF2421/HF2321/HF9111/HF5122。
7. 接入建议
7.1 发现方(桌面端)
- 广播地址用
255.255.255.255,端口 48899;本机有多块网卡时每块各广播一次(实测抓到 2 个包,间隔 64ms)。 - 发送消息体直接照抄上面那段 JSON,务必保留
ConnectMode":"Forbidden", 否则可能被误当成「配置指令」改写设备的服务器地址。 - 用同一个 socket 发广播并收回复(绑临时端口);发完等 ~1 秒再收, 不要用 48899 去 bind 收回复。
- 按
MAC去重:同一台设备会因为收到多个广播地址而回多个包(实测 2 个/次)。 - 设备名按 UTF-8 解码(
HostName实测含中文「8号」)。 - 扫描周期参考 3 秒,设备 30 秒无回复即标记离线。
- 若收不到回复,优先排查 AP/交换机是否开了客户端隔离(AP isolation)。
7.2 设备端(本工程 AndroidStation)
AndroidStation 扮演的是「网口扫码设备」这一侧:
- UDP 48899:
DiscoveryResponder绑定 48899,收到{"Type":"EP_Tool",...}就按 §6 的字段 回复自己的MAC / HostName / Type / Version / Uptime / State。回复走同一个 socket, 源端口就是 48899。 - TCP 8087:
ScanServer监听服务端口(默认 8087,与桌面端ScanProtocol.TcpPort一致), 桌面端主动连上来;USB 扫码结果按 CRLF 结尾的 UTF-8 行推送。桌面端连上后下发的 扫码枪串口设置指令会被读取并丢弃(本机是 USB HID,不做串口透传)。 - JCMD:兼容桌面端「添加通道」用到的
10001 / 10003 / 10005 / 10017:10003 + PL:["SOCK"]→ 返回一条packcenter / TCP-SERVER / 8087;10003 + PL:["SYS"]→ 返回HostName / IpAddr / DhcpEn=1等只读信息;10005写SYS.HostName会更新设备名;写SOCK.LocalPort会改本地服务端口并重启监听;10017直接确认(设置已经落到 SharedPreferences);20003只确认,不重启本机。
- 不改 IP:本机不提供网络参数写入,
SYS里的地址只读上报。 - 只需
INTERNET权限(UDP/TCP 都是普通 socket,不需要系统应用权限)。
8. 待复验
设备回复的确切内容→ 已实测:明文 JSON,188~189 字节,见 §6- 定向查询(带
DevMac)的回复是否包含productID/swVer/Local/position等字段 - 设备管理端口 5555 的 10 字节命令格式
- 设了密码的设备是否真的走 AES,密钥是否就是那个硬编码值
- 是否存在只回包不响应广播的设备(即必须先定向查询)
9. 控制命令(JCMD)[实测]
发现之后的配置/控制走同一套机制。证据来自官方工具 V2 的运行日志
(IOTService\IOTService_V2\logs\log.log):
SendJcmd(289C6E833560):{"JCMD":1,"PL":["SYS","UART","SOCK"],"CID":10001},to:169.254.1.1/48899
Recv:{"CID":10002,"RC":0,"Remain":1,"PL":{"SOCK":[...]}}
SendJcmd(289C6E833560):{"JCMD":1,"Remain":1,"CID":10002},to:169.254.1.1/48899 ← 没取完就继续要
Recv:{"CID":10002,"RC":0,"Remain":0,"PL":{"SYS":{...}}}
传输
- UDP 单播到设备自己的 IP,端口 48899(与发现同一个端口)。
实测 604 次
SendJcmd全部发往 48899。 - 不需要握手,发现完直接发。
- 靠目标 IP 区分设备,请求里不带
MAC。
报文结构
请求:
{"JCMD": 1, "CID": <命令号>, "PL": <可选载荷>, "Remain": <可选,取后续分片时带>}
响应:
{"CID": <响应号>, "RC": <错误码>, "Remain": <0|1>, "PL": <可选载荷>}
RC = 0表示成功(JCMD_ERR_SUCCUSS)。Remain = 1表示设备还有后续分片,客户端要用 响应 CID 再发一次带Remain:1的请求, 直到Remain = 0。这就是状态查询要来回多次的原因。
CID 命令表(iotservice.device.jcmd.Jcmd,javap 读出)
| CID | 名称 | 说明 |
|---|---|---|
| 10001 / 10002 | JCMD_GET_STATE |
取状态(PL:["SYS","UART","SOCK"]) |
| 10003 / 10004 | JCMD_GET_CONFIG |
取配置 |
| 10005 / 10006 | JCMD_SET_CONFIG |
写配置 |
| 10007–10010 | *_CONFIG_XML |
读/写 XML 配置 |
| 10011 / 10012 | JCMD_WIFISCAN |
WiFi 扫描 |
| 10013–10018 | *_SCRIPT / *_FSETTING |
脚本与出厂设置 |
| 10019–10022 | *_FLASH_PARA |
Flash 参数 |
| 10023 / 10024 | JCMD_GET_NLOG |
取运行日志 |
| 20001 / 20002 | JCMD_DO_RELOAD |
重载配置 |
| 20003 / 20004 | JCMD_DO_RESTART |
重启设备 |
| 20005 / 20006 | JCMD_DO_UPGRADE |
固件升级 |
| 20009–20012 | JCMD_MODBUS_* |
Modbus 读写 |
| 30001 / 30002 | JCMD_DO_DATASEND |
透传发数据 |
| 40001 / 40002 | JCMD_LOG |
日志 |
| 90000 | JCMD_CONNECTED |
连接标记 |
错误码:RC = 0 成功;1 失败;2 需要 PL;3 需要 SockName;4 还有更多;
5 JCMD 被占用;6 已断开;7 超时;8 无需操作。
系统配置读写(已实现,实机验证通过)
读配置:CID 10003 → 10004
-> {"JCMD":1,"PL":["SYS"],"CID":10003}
<- {"CID":10004,"RC":0,"Remain":0,"PL":{"SYS":{...}}}
PL是段名数组。只要 SYS 就传["SYS"](实测可用,返回也更小); 官方工具传的是["SYS","UART","SOCK"]。Remain=1时用响应 CID 续取:{"JCMD":1,"Remain":1,"CID":10004}。 实测 E10C 读 SYS 一次返回,不分片。
SYS 字段(实测 E10C 全字段):
| 字段 | 示例 | 说明 |
|---|---|---|
User / Password |
admin / admin |
Web/Telnet 登录账号,明文返回 |
HostName |
8号 |
设备名(UTF-8) |
DhcpEn |
0 |
0 = 静态,1 = DHCP |
IpAddr |
192.168.9.208 |
IP 地址 |
Mask |
255.255.252.0 |
掩码——字段名是 Mask,不是 NetMask |
GateWay |
192.168.8.1 |
网关(注意 G/W 大写) |
Dns |
192.168.8.1 |
DNS |
| 其余 | Telnet* / Web* / Ipv6* / ntp* / ModbusTime / Longitude / Latitude / Lang |
⚠️ 字段集因型号而异:官方日志里另一台设备还有
NetworkMode/WiFi*/LanIpAddress/LanMarsk/EthernetMode/SmartConfig,而这台 E10C 没有。
切到 DHCP 的实测行为(2026-10-15)
{"JCMD":1,"PL":{"SYS":{"DhcpEn":1}},"CID":10005} + 保存:
-
不需要重启就生效(实测
Uptime未归零)。 -
设备保持原 IP 可达(本例仍是
192.168.9.208;不排除是 DHCP 恰好分配了同一地址)。 -
⚠️
IpAddr/Mask/GateWay会被清零成0.0.0.0,Dns保留。 所以改回静态时这三个字段必须一起写,只写DhcpEn=0会让设备拿0.0.0.0跑:-> {"JCMD":1,"PL":{"SYS":{"DhcpEn":0,"IpAddr":"192.168.9.208", "Mask":"255.255.252.0","GateWay":"192.168.8.1","Dns":"192.168.8.1"}},"CID":10005} -
兜底手段:换 IP 后设备仍在 48899 上广播,所以「广播发现」是把设备找回来的可靠方式。 实测
tools/device-restart.ps1(不带参数)就能找回并列出当前 IP。
写配置:CID 10005 → 10006,增量
-> {"JCMD":1,"PL":{"SYS":{"Dns":"192.168.8.1"}},"CID":10005}
<- {"CID":10006,"RC":0}
只传要改的字段。不要回传整份配置:字段集因型号而异,整份回写会把设备上 本应用不认识的字段一并覆盖掉。
DO_RELOAD:CID 20001 → 20002 —— ⚠️ 不是「应用配置」,不要用
-> {"JCMD":1,"PL":["SYS","UART","SOCK"],"CID":20001}
<- {"CID":20002,"RC":0}
官方工具里 Reload 是设备状态窗口上一个独立按钮(ui/DlgStatus.btnReload,
确认文案 "Do you want to do Reload?"),与 Restart、F-Set Clear / Default Setting
(对应 JCMD_SET_FSETTING 10017)是三个不同动作,所以它不是恢复出厂。
但它也不是「让配置生效」——实测它会把改动抹掉。同一台设备上写 HostName 的对照实验:
| 操作 | 读回结果 |
|---|---|
写入 + DO_RELOAD |
Eport-E10C(出厂默认)❌ 改动丢了 |
| 只写入、不 reload | 8号工作台 ✅ |
| 只写入 + 重启设备 | 8号工作台 ✅(重启后 Uptime 归零,确认真的重启过) |
- 佐证:官方工具里有一条文案
Config OK! And Restart Device.——改完配置,官方期望的是重启,不是 reload。 - 所以本项目的做法是:
SET_CONFIG写完就结束,什么都不补。SET_CONFIG会落盘并对重启免疫,不需要额外动作。
两个附带观察(机制均未确认):
DO_RELOAD之后ModbusTime从0变成-1; 本项目发的Restart(CID 20003)在设备上延后几分钟才真正复位 (探测期间Uptime从3:12掉到0:40)。
AndroidStation 侧:只处理 SYS.HostName 与 SOCK.LocalPort,其余网络字段只读上报。
PC 侧:tools/device-config.ps1(读直接执行;写要 -Yes;不要加 -Reload)。
重启设备(已实现,实机验证通过)
发 {"JCMD":1,"CID":20003} ← 无 PL
收 {"CID":20004,"RC":0}
实测日志片段:
13:17:25 SendJcmd(289C6E833560):{"JCMD":1,"CID":20003},to:169.254.1.1/48899
13:17:25 Restart Device 289C6E833560
13:17:25 Recv:{"CID":20004,"RC":0}
13:17:25 BroadCast:1 ← 重启后工具暂停广播
13:17:30 BroadCast:0 ← 5 秒后恢复
设备应答后才会真正重启,重启期间会失联一段时间,发现列表里会自然变为离线。
AndroidStation 侧:收到 20003 只回 RC=0,不会重启本机(设备端要保持服务在线)。
PC 侧:tools/device-restart.ps1(默认演练,加 -Yes 才真发)。
附:复现命令
# 被动监听:只能看到工具/自己发出的广播请求
powershell -NoProfile -ExecutionPolicy Bypass -File tools\udp-listen.ps1 -Minutes 3
# 主动探测:自己发广播并在同一 socket 收回复(发现设备用这个)
powershell -NoProfile -ExecutionPolicy Bypass -File tools\udp-listen.ps1 -Probe -Minutes 2