# 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 ```