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

381 lines
17 KiB
Markdown
Raw Permalink 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.

# 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,无换行):
```json
{"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**:
```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. 待复验
- [x] ~~设备回复的确切内容~~ → 已实测:明文 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`。
### 报文结构
请求:
```json
{"JCMD": 1, "CID": <命令号>, "PL": <可选载荷>, "Remain": <可选,取后续分片时带>}
```
响应:
```json
{"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
# 被动监听:只能看到工具/自己发出的广播请求
powershell -NoProfile -ExecutionPolicy Bypass -File tools\udp-listen.ps1 -Minutes 3
# 主动探测:自己发广播并在同一 socket 收回复(发现设备用这个)
powershell -NoProfile -ExecutionPolicy Bypass -File tools\udp-listen.ps1 -Probe -Minutes 2
```