packServer/AndroidStation/docs/udp-48899-protocol.md
liufumingren 228723e0c3 设备端扫码上报 + 桌面端/Android 正式包发布脚手架
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>
2026-10-21 05:53:27 +08:00

17 KiB
Raw Blame History

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   ← 切到设备管理端口

所以完整流程是:

  1. PC 广播 JSON → 255.255.255.255:48899(多网卡时每个广播地址各发一次)
  2. 设备回一段明文 JSON 给发送方(实测 188~189 字节,见 §6)
  3. 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 发现方(桌面端)

  1. 广播地址用 255.255.255.255,端口 48899;本机有多块网卡时每块各广播一次(实测抓到 2 个包,间隔 64ms)。
  2. 发送消息体直接照抄上面那段 JSON,务必保留 ConnectMode":"Forbidden", 否则可能被误当成「配置指令」改写设备的服务器地址。
  3. 用同一个 socket 发广播并收回复(绑临时端口);发完等 ~1 秒再收, 不要用 48899 去 bind 收回复。
  4. 按 MAC 去重:同一台设备会因为收到多个广播地址而回多个包(实测 2 个/次)。
  5. 设备名按 UTF-8 解码(HostName 实测含中文「8号」)。
  6. 扫描周期参考 3 秒,设备 30 秒无回复即标记离线。
  7. 若收不到回复,优先排查 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