扫码终端配置与接入使用文档

功能与使用流程

扫码终端负责识别二维码并上传内容，接收服务器负责解析数据并返回处理结果。服务器返回处理结果后，终端再根据自身固件和配置执行亮灯、蜂鸣、语音或继电器动作。

本工具提供独立的终端配置、音频制作及 USB 写入功能。使用者可以填写自己的接收地址，将终端接入任意符合设备通信协议的系统。工具网站本身不接收终端上传的扫码数据。

推荐操作顺序

1. 确认设备型号、固件和网络条件，准备有效的接收地址。
2. 在“终端配置”生成二维码，用目标终端扫描；按设备要求重启并检查是否联网。
3. 进行一次扫码上传，确认服务端收到二维码内容和正确设备号。
4. 在“播报语音”编辑文案，选择音色和采样率，生成音频包。
5. 通过“USB 连接与写入”读取版本、准备语音包并写入。
6. 断电重启，逐项测试开机、扫码、成功、失败及接口返回码对应的播报。

开始前的准备

需要准备的信息和设备

网络条件

局域网调试时，终端与接收服务器需要位于可互通的网络中。生产接入时，终端所在网络需要能解析并访问配置的服务器域名和端口。电脑能打开网页，并不等于终端一定能访问该接口，应以真实扫码上传为准。

原厂 Wi-Fi 教程明确提示：其所述 Wi-Fi 版本使用动态 IP，配置静态 IP 会导致无法联网。因此，Wi-Fi 设备优先使用路由器 DHCP 分配地址。教程另有开发模式静态 IP 示例，不能据此推定所有 Wi-Fi 型号都支持静态 IP；本工具也不提供静态 IP 设置。

部分设备从外观无法判断是否连接 Wi-Fi。可以在路由器客户端列表中核对新增设备、MAC 地址及分配的 IP。设备名称可能显示为星号或 unknown，不能仅凭显示名称判断归属。

配置扫码终端

“终端配置”用于生成可由设备扫描的配置二维码。它会将网络、亮度、设备号和接收地址编码成原 VBAR 配置格式，再用设备配置密码签名。二维码生成成功代表格式已生成，不代表终端已经应用配置或接收接口已经接通。

填写参数

生成并应用配置

1. 给终端正常供电，确认终端具备网络扫描配置能力。
2. 填写并复核上述信息，点击“生成配置二维码”。
3. 使用准备配置的那台扫码终端扫描网页显示的二维码。
4. 根据设备反馈确认已接收配置，再按设备要求断电重启。
5. 在路由器后台核对联网情况，并扫描一个普通测试码，检查服务端是否收到上传。
6. 确认设备号与预期一致，再进行接口返回码与设备行为测试。

更换 Wi-Fi、接收地址或设备号后，需要重新生成并扫描配置二维码。网页中修改字段不会自动改变终端。二维码包含网络密码及接口信息，操作完成后可点击“清除二维码”；不要公开分享配置二维码。

当前配置模板的范围

当前模板使用已适配的网络工作参数，配置协议标识为 ___VBAR_CONFIG_V1.1.0___，并使用 haddr 写入 HTTP 类接收地址。模板含 5 秒接口超时和 1000 ms 继电器延时等固定值，但这些值并非网页中的独立调节项；实际动作还受硬件及固件支持影响。需要 TCP、开发模式或其他硬件动作组合时，应先完成对应协议适配，不能用修改 URL 的方式替代。

制作播报语音

本工具直接将中文文案合成为设备音频，不需要另外录音或使用格式转换软件。修改文案只改变声音内容，不改变返回码含义或固件行为。

选择音色和采样率

可选择晓晓、晓伊两种女声，以及云希、云健两种男声。点击“试听音色”生成一段统一的示例语音，用于比较音色。试听播放的是示例句，不是当前 14 段文案，也不代表设备扬声器的最终音质。

“音频采样率”默认选择 11025 Hz · 原厂教程，与原厂音频制作说明一致。另有 16000 Hz · 兼容选项，仅用于已经确认兼容该采样率的设备。首次配置优先选择 11025 Hz，写入后必须实机试听。

编辑文案并生成

1. 选择音色和适合设备的采样率，按需试听示例语音。
2. 设置“扫描微信付款码时播报”和“扫描其他二维码时播报”两个开关。
3. 展开“编辑全部 14 段文案”，逐项修改对应槽位的文案。
4. 点击“生成并下载 ZIP”，保存可解压查看的 WAV 音频文件。
5. 等待生成结果；成功提示会显示 WAV 总大小，下载文件由浏览器保存到本机。
6. 通过 USB 直接写入时，无需先下载 ZIP；在下一节连接设备并准备当前语音包即可。

两个播报开关通过生成静音的 2.wav 或 3.wav 实现；它们不改变设备的扫码识别功能，也不替代固件中的播报开关。1.wav 不受这两个开关控制。即使开启，仍需设备固件触发相应槽位才能播放。

声音文件与返回码

以下映射适用于原音频教程所述的普通语音设备。文件名是固件识别槽位的依据，不是任意命名的标签。接口接入时，应先约定每个返回码的含义，再填写对应文案。

正确区分扫码提示和接口结果

扫码提示表示终端识别到某类二维码；接口结果表示服务器返回的处理状态，两者属于不同阶段。播报文案应与实际触发条件一致，例如将扫码提示设为“已识别”，将成功应答提示设为“处理完成”。

网络接口规范将 0000 定义为成功、其他结果码定义为错误；音频教程又列出了 0001 至 0008 的专用播报槽位。因此，非零码有可播放语音，不代表它具有成功码的设备动作语义。需要继电器或其他成功动作时，应结合具体固件测试，不要只看播报是否符合文案。

各返回码的具体含义由接入方约定，厂商提供的是声音文件与返回码的对应关系。例如，将 0002 约定为“数据格式不正确”时，对应编辑 10.wav，并保持服务器应答与播报内容一致。

通过 USB 写入语音

USB 写入由浏览器直接连接当前电脑上的设备完成。网站服务器负责制作语音包，实际 USB 通信发生在本机；远程服务器无法替你连接现场终端。

确认连接条件

• 通过 https://scan.hlbe.net 打开工具，建议使用 Windows Chrome。浏览器须提供 WebHID 能力。
• 使用能传输数据的 USB 线，保持终端供电稳定。关闭可能占用同一设备的其他程序。
• 原厂教程要求普通 USB 模式并在切换后重启。本工具当前不提供工作模式切换；若设备没有暴露兼容 HID 接口，需先由设备维护方完成相应模式准备。
• 当前设备选择器使用 VID 0525、PID A4AC，并校验原协议所需的 1024 字节输出报告。其他型号即使有 USB 接口，也不代表可以直接使用。

读取版本

1. 将目标终端接入电脑，点击“连接并读取版本”。
2. 在浏览器设备选择窗口中选择对应终端并授权连接。
3. 等待页面显示产品名称和设备版本。只有版本读取成功，才会开放“准备当前语音包”。
4. 若无法找到设备或版本查询超时，先解决连接问题，不要反复尝试写入。

准备并写入

1. 复核上方音色、采样率、播报开关及全部文案。
2. 点击“准备当前语音包”，等待页面显示包大小和“尚未写入”。此步骤只制作待写入文件。
3. 点击“写入扫码终端”，核对确认提示后开始写入，期间不要拔线或断电。
4. 工具会尝试暂停设备看门狗、发送语音包，再恢复看门狗，并显示写入进度或错误状态。
5. 收到设备确认后，按提示断电重启，测试开机音和各结果码槽位。页面确认不替代设备重启后的实际播放验收。

准备后修改任何文案、音色、采样率或播报开关，均须重新准备语音包。工具不会让旧包在设置变化后继续作为当前包写入。重新连接设备后，也需要重新准备。

异常恢复

出现“写入未确认”时，应将状态视为结果未知，先检查设备实际情况，再决定是否重试。若提示看门狗恢复未确认，按页面提示对终端断电重启并检查。原厂教程要求“工具成功提示”与“设备三声蜂鸣”共同确认；若设备没有对应反馈或新语音未生效，应优先核对格式、模式、包内容和固件兼容性。

HTTP 接口接入

终端作为 HTTP 客户端向接收服务器提交扫码结果，服务器返回纯文本处理结果。接收接口与本工具的设置页面是两个不同入口。下面的路径和设备号均为示例，实际部署需要替换。

地址与请求方式

http://serveraddr:port/path
https://serveraddr:port/path

POST /api/scan/
Content-Type: text/html; charset=UTF-8

vgdecoderesult=TEST123&&devicenumber=1001

原网络接口规范给出的地址形式为 HTTP。HTTPS 是否可用应以终端固件及证书支持情况为准。服务器需读取请求正文中的原始字符流，不应假定设备会发送 JSON，也不能只因正文类似表单就依赖标准表单解析。

成功应答与结果播报

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8

code=0000

code=0000 为协议成功。普通协议模式下，终端收到该应答后执行已配置的成功行为；DW100 的继电器、MC100 的语音等具体能力由对应型号决定。返回 code=0001 至 code=0008 时，普通语音设备按前文表格选择相应声音槽位。

HTTP 状态码 200 与设备正文结果码是不同层次：只有一个空的 200 响应，不能代替 code=0000。接收接口也不宜跳转到登录页或其他地址，设备可能无法按浏览器方式跟随跳转。

超时与服务端处理

本工具当前配置模板将 HTTP 等待时间设为 5 秒。服务器应在设备等待时间内返回明确结果。长时间处理、网络失败或不返回时，终端可能执行失败行为；设备超时并不能证明服务端处理没有完成。

生产接入建议单独处理设备认证、请求校验和重复提交。服务器应能够识别重复请求，并提供处理状态查询，避免因重复扫码或响应丢失而重复执行。原接口规范没有提供完整认证和幂等协议，需要接入方自行设计。

原规范还列出 LuaSocket、Connection、Accept 等示例请求头，以及一组示意性的 Content-length。不要将示例长度照搬到实际请求，实际正文长度以收到的字节为准。

带屏设备与图片

原音频资料还包含带屏型号的图片设置，但本工具目前只提供音频制作和语音包写入，没有图片上传、图片压缩、屏幕资源打包或显示指令功能。本节保留资源规则，供兼容性核对及后续适配使用。

wav/
  0.wav
  1.wav
  2.wav
  3.wav
  s.wav
  f.wav
  logo.png
  bk.png
  protocol/
    1.png
    2.png
    3.png
    4.png

以上目录结构来自带屏型号的资源示例，不是当前工具实际生成的包内容。当前语音包只有前文列出的 14 个 WAV 文件，不会包含 Logo、背景图或 protocol/ 图片目录。

带屏型号的声音槽位差异

普通语音设备说明将 1.wav、2.wav、3.wav 分别关联支付宝付款码、微信付款码及非付款码；带屏设备截图则将它们标为“语音 1 / 2 / 3，由指令控制播放”。二者不能直接混用。针对带屏型号，应先确认对应固件的声音编号和显示指令，不能把普通设备的返回码映射直接当作通用规则。

接线资料的使用范围

原音频资料给出 USB 数据线颜色与信号的对应关系：红色为 5V/VCC、黑色为 GND、绿色为 DATA+、白色为 DATA−。颜色仅为原示例，实际接线前必须核对设备端子定义及线序；不得仅凭颜色带电接线。优先使用厂家成品数据线。

其他端子的用途、供电要求和负载电气参数应以对应型号的厂家图纸为准。本工具不提供硬件接线配置，连接外部设备前应核对完整端子定义。

完整接入示例

以下用普通文本二维码示例说明工具、终端与接收服务器的配合方式。接收服务器示例地址为 https://example.com/api/scan/，设备号为 1001，实际使用时必须替换。

先准备接收接口

接收 vgdecoderesult 和 devicenumber。约定测试内容 TEST123 有效时返回 code=0000；其他测试内容返回 code=0002。服务器先完成校验，再返回设备可解析的纯文本。

配置网络和设备号

打开“终端配置”，填写设备号 1001、真实接收地址、现场 Wi-Fi 及厂商配置密码，选择亮度并生成配置二维码。目标终端扫描后重启，在服务端确认上传携带正确设备号。

配置对应播报

打开“播报语音”，默认选择 11025 Hz。将 s.wav 改成“数据接收成功”，将 10.wav 改成“测试内容不匹配”，将 f.wav 改成“连接失败，请联系工作人员”。如果不需要扫码后立即播报，可关闭两个扫码提示开关。准备并写入语音包后重启。

进行三组验证

完成测试后，使用目标系统实际接收的数据格式继续验证。正式使用前替换示例 TEST123 和 example.com，并记录已通过测试的返回码及终端反馈。

常见问题排查

优先按“设备是否联网 → 是否成功上传 → 应答是否正确 → 固件动作是否匹配 → 音频是否写入生效”的顺序定位，避免同时改动多个参数。

配置验收与维护

网络与接口验收

• 终端重启后能重新连接目标 Wi-Fi，并能访问接收接口。
• 服务端收到的二维码内容完整，设备号与登记一致。
• 成功、各接口结果码及超时场景均有明确、可重复的反馈。
• 实际处理结果与返回码一致，重复扫码和超时重试不会造成非预期的重复执行。
• 网络恢复后能够继续使用，异常结果可以通过服务端记录查证。

音频验收

• 开机音、扫码提示、s.wav、f.wav 以及实际使用的 0001 至 0008 槽位均逐项验证。
• 声音清晰，无无法播放、截断或明显失真；关闭的扫码提示保持静音。
• 断电重启后仍使用新语音，未出现只在写入当次有效的情况。
• 涉及不同型号或固件时分别验收，不用某一台设备的结果推定全部设备兼容。

建议留存的配置记录

记录设备型号、设备号、固件版本、部署位置、接收地址、配置日期、操作者、音色、采样率、文案版本、下载包名称及验收结果。Wi-Fi 密码、设备配置密码和带凭据的接口地址应按受限配置管理，不放入公开文档、截图或代码仓库。

更新语音前，保留已验收的音频包和对应文案；工具目前不提供读取或备份终端原有语音的功能。配置多台设备时逐台连接、核对版本并验收，避免把准备给另一台设备的配置二维码误扫到当前设备。

修改接口返回码语义时，同步更新服务端约定、声音文案和测试清单。修改 Wi-Fi 或接收地址时重新生成配置二维码；修改音频时重新准备并写入，二者互不替代。

兼容性与资料依据

以实际工具能力为准

本工具适配 VBAR 配置格式及对应 HID 写入流程，不是任意品牌扫码器的通用驱动。网页生成成功、软件测试通过和设备实机通过是不同层次，新的型号或固件应先小范围验证。

原厂音频教程给出的基准是 WAV、单声道、11025 Hz，未完整明确位深和所有容量限制；本工具采用 16-bit PCM，并将 1,000,000 字节以下作为当前实现的容量限制。16000 Hz 是工具保留的兼容选项，不作为原厂教程的通用要求。

当前尚未覆盖屏幕图片资源写入、开发模式命令发送、TCP 配置、固件升级、终端音频回读、硬件接线及所有型号的兼容验证。文档保留相应技术背景，是为了明确接入边界，不表示网页已经提供这些操作。

资料索引

设备操作以本工具当前网页为入口。原厂软件截图及其点击步骤未作为本工具操作步骤保留；涉及原资料未完整定义或不同型号有差异的部分，已在相应章节标明适用条件。