设置门卡编码器

快速设置

选择编码器类型，按需选择连接方式，然后添加编码器。 预计用时约 15 分钟。

本指南帮助你为 kiosk 或前台配置编码器优先的门卡编码流程。 现在也涵盖 Be-Tech Windows Agent 的设置。 除非配置了直连 Base URL，否则 Be-Tech 默认使用 Windows Agent。 Kiosk 路由现在位于 Settings → Kiosk。 PMS 集成门卡会在添加编码器前，先从 PMS 供应商发现编码器终端。 Be-Tech Windows Agent 设置可以在 Windows 重启或手动停止后恢复已停止的客户端或服务。 对于受支持的供应商，AVA 会从 Room Access Service 加载可用字段、连接规则和路由选项。 因此，标签和必填字段可能因供应商或部署方式而异。

快速参考

任务	作用	点击位置
Select method	启用门卡编码	Room Access → Keycard Encoding
Choose encoder type	选择锁系统	Encoder Type
Choose connection method	直连或 Windows Agent（Saflok/Be-Tech/GreatLocks）	Advanced options → Enable direct communication
Configure encoder	添加服务器或凭据信息	特定类型的字段
Add encoders	使用真实编码器 ID 注册物理设备	Physical Encoder Devices
Load PMS encoders	从 PMS 获取可用终端	Physical Encoder Devices → Load Encoders
Enable PMS card reading	允许 Entitlements 读取实体 PMS 门卡	Enable physical keycard reading
Choose kiosk routing	控制 kiosk 专用路由规则	Settings → Kiosk → Device Routing
Download Windows Agent	下载 agent 的引导包	Windows Agent
Check agent version	显示已安装版本和最新版本状态	Windows Agent
Update agent	打开更新说明弹窗	Update
Manage agent cards	主卡片显示安装、更新或重装操作	Windows Agent
Advanced agent actions	查看日志、轮换密钥或删除 agent	Advanced options
Set encoding defaults	每次入住的卡片数量 + 过期时间	Encoding Options

在哪里找到

Settings → Room Access → Keycard Encoding

第 1 步：选择门卡方式

1. 前往 Settings → Room Access。
2. 将房间访问方式选择为 Keycard Encoding。
3. 点击 Save。

第 2 步：选择编码器类型

1. 滚动到 Keycard Encoder Settings。

2. 选择 Saflok、Be-Tech、LockSDK、GreatLocks、Adem 或 PMS Integration。

   ✓ AVA 只会保留你所选的编码器类型处于启用状态。

第 3 步：选择连接方式

1. 在 Select Encoder Type 中打开 Advanced options。
2. 对于 Saflok、GreatLocks 或 LockSDK，打开 Enable direct communication 以绕过 Windows Agent。
3. 保持关闭则使用 Windows Agent（默认）。
4. Be-Tech 默认使用 Windows Agent，除非已配置直连 Base URL。
5. PMS Integration 仅使用直连，因此跳过此步骤。

第 4 步：配置编码器系统

编码器凭据标题

如果使用多个编码器，区域标题会显示为 Encoder Credentials & Devices。

如果使用 Saflok

• Direct communication
  • 输入 PMSI Server URL、Username 和 Password。
  • PMSI 服务器必须可以从互联网访问。
  • 点击 Test Connection。
• Windows Agent
  • 仅输入 Username 和 Password。
  • PMSI URL 和连接测试由 agent 处理。
  • AVA 会持续重新检查 Saflok PMSI 是否就绪，因此启动缓慢和重启通常会自动恢复。
• 在 Physical Encoder Devices 中添加编码器设备（需要 Encoder ID）。
• 可选：为每个编码器设置 Location。
• 如果多个 kiosk 共用编码器，请从 Settings → Kiosk → Device Routing 添加路由。

如果使用 Be-Tech

• Direct communication
  • 输入 Be-Tech 服务的 Base URL。
  • 该服务必须可以从互联网访问。
  • 输入 Hotel Name、Chain No、Workstation 和 Reader No。
  • 如果 Be-Tech 设置需要，请设置 Category 和 Card Type。
  • 如果已保存 Base URL，AVA 会让 Be-Tech 保持直连模式。
  • 点击 Test Connection，确认编码器有响应。
• Windows Agent
  • 在连接到 Be-Tech 工作站的 Windows 电脑上安装 agent。
  • 输入 Hotel Name、Chain No、Workstation 和 Reader No。
  • agent 处理本地 Be-Tech 适配器，并代理供应商流量。
  • AVA 每 5 分钟在 /check 上检查 agent。
  • Windows 重启或手动停止后，托盘程序可以自动启动 Be-Tech 客户端和服务。
  • 恢复后，托盘程序会刷新 Be-Tech 就绪状态，无需手动重启 agent。
  • 如果没有保存 Base URL，AVA 会回退到 Windows Agent 流程。
• 在 Physical Encoder Devices 中添加编码器设备。
• 如果使用多个编码器，可选从 Settings → Kiosk → Device Routing 添加路由。

多个 Be-Tech 安装

agent 会自动发现普通的 Be-Tech 安装。 仅当多个受保护安装造成歧义时，才请部署管理员设置 BETECH_CLIENT_PATH。 该覆盖路径必须指向受保护的 Windows Program Files 文件夹内。

如果使用 GreatLocks

• Direct communication
  • 输入 Server Name（可选）、XHLSI Server IP Address 和 TCP Port。
  • 服务器必须可以从互联网访问。
  • GreatLocks 每个服务器支持一台编码器。
  • 点击 Test Connection。
• Windows Agent
  • 服务器详情由 agent 处理；无需 IP/端口。
  • 在连接到每台 GreatLocks 编码器的电脑上安装一个 Universal Encoder Agent。

每台编码器使用一个 GreatLocks agent

每台 GreatLocks 编码器都要在 Physical Encoder Devices 中添加一行。 每行准确输入一个 Encoder ID。 每行使用唯一 ID，例如 front-desk 或 lobby-pc。 编辑已保存的行时，AVA 会保留现有 ID。 没有 ID 的旧行会在 AVA 加载时获得稳定 ID。 然后在对应的 Windows 电脑上安装一个 Universal Encoder Agent。 每个 agent 只服务于与其关联的编码器。

注意： AVA 使用你在 Room Access 中保存的 GreatLocks 服务器记录。 如果更新了旧设置，请在 Test Connection 前点击 Save。 如果启用了库存同步，AVA 会通过活动 agent 隧道读取建筑、楼层和房间数据。 保持 agent 在线，以便房间列表保持最新。 如果 GreatLocks 设置支持电梯访问，请打开 Enable lift access。 然后选择供应商支持的模式：

• Room floor mapping 使用房间映射中的建筑和楼层值。
• Access code groups 使用 Common access codes 处理共享门或电梯组。

AVA 每张卡只发送一种电梯选项类型。 使用访问代码组时，AVA 会将单个数字保存为两位数代码。 你可以输入 1,2,3 或 01,02,03。 代码必须处于供应商支持的范围内。

如果使用 LockSDK

• Direct communication
  • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
  • 为每台编码器输入 Encoder ID 和 Service URL。
  • 添加编码器条目后点击 Test Connection。
• Windows Agent
  • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
  • 为每台 LockSDK 编码器注册一个 Windows Agent。
  • agent 卡片显示匹配的编码器和实时状态。
• 如果使用多个编码器，可选从 Settings → Kiosk → Device Routing 添加路由。
• 对于合并房间，LockSDK 最多支持 4 个房间，并要求 RF50/Mifare lock type 5。

如果使用 Adem

Adem 编码器设置

Adem 使用 Windows Universal Encoder Agent 加载其 32 位 SDK。 agent 软件包不会安装 Adem 锁系统服务器、读卡器驱动程序或编码器。 AVA 会从 Room Access Service 接收 Adem 字段、编码器录入规则、连接模式和 agent 注册选项。 如果你看到的字段与此示例不同，请按照屏幕上显示的字段操作。

1. 在 Encoder Type 下选择 Adem。

2. 选择部署方式显示的连接方法。 对于编码器电脑，通常选择 Windows Agent 模式。

3. 输入 1 至 6 之间的 Lock Software。

4. 输入 8 或 9 作为 Version。

5. 输入 Adem 的 Server 名称和 Log User。

6. 在测试连接前点击 Save。

   ✓ AVA 会在保存前验证必填的 Adem 设置。

7. 打开 Physical Encoder Devices，然后点击 Add Encoder。

8. 输入唯一的 Encoder ID，以及可选的 Name 和 Location。

9. 输入编码器的 Port。

Port	含义
0	原生 USB 读卡器
1	COM1
2	COM2
3	COM3

10. 对于串行读卡器，使用实际的 Windows COM 编号。
11. 在直连模式下，为每台编码器输入 AVA 显示的服务 URL。 只有所选连接模式要求时，才需要此字段。
12. 点击 Save，然后点击 Test Connection。

✓ AVA 会先保存当前 Adem 设置，再测试已持久化的配置。 ✓ 更改供应商、SDK 设置、编码器条目或路由后，之前的测试结果会失效。

Adem agent 共享规则

一个 Windows Agent 可以为多台串行编码器提供服务。 每台编码器必须使用不同且大于 0 的 COM 端口。 不支持在一个 agent 上连接多台原生 USB 读卡器。 对于静态连接，共用一个 agent URL 的条目也遵循相同规则。 不同的编码器电脑可以使用相同的 COM 编号，因为该编号仅对各自电脑有效。

13. 在编码器电脑上下载并安装生成的 Windows Agent 软件包。
14. 从 Windows Agent 部分注册 agent。
15. 使用 AVA 显示的路由选项分配可用的 Adem 编码器和 kiosk。 当 Room Access Service 启用共享注册时，一个共享 agent 可以为多台 Adem 编码器提供服务。
16. 当 AVA 引导你前往此处时，在 Settings → Kiosk → Device Routing 下注册 kiosk。
17. 如果 PMS 房间名称不同，请在 Keycard Room Mapping 中将其映射到 Adem 房间编号。

编码前验证 Adem 读卡器

当你需要从 Windows 编码器电脑获取证据时，请使用随附的诊断辅助工具。 该辅助工具不会编码或擦除门卡。

1. 在编码器电脑上打开 32 位 Windows PowerShell。

   C:\Windows\SysWOW64\WindowsPowerShell\v1.0\powershell.exe -NoProfile

2. 在 AVA 中分配 COM 端口前，盘点本地 COM 端口。

   .\scripts\test-adem-encoder.ps1 -Json

   仅在工作人员一次连接一台未使用的读卡器时使用 -Watch。 驱动程序名称只能识别 Windows 设备，不能确认它们是 Adem 读卡器。

3. 将已确认的 COM 编号保存到 AVA 中每台编码器的 Port 字段。 COM 编号属于该 Windows 电脑，而不是逻辑上的 Encoder ID。

4. 可选：在不插卡的情况下读取指定端口。 使用酒店实际的 Adem 软件、版本和 SQL 服务器值。

   .\scripts\test-adem-encoder.ps1 -Read -Port 3,4 `
     -AppRoot 'C:\Vouch\Universal Encoder Agent' `
     -LockSoftware 2 -Version 9 -Server 'LOCK-PC' -EncoderIdle -Json

   辅助工具会依次读取选定端口，并要求明确确认 -EncoderIdle。 执行此探测期间不要编码门卡，也不要使用供应商读卡器。

5. 查看 SessionSucceeded、每个端口的 Code 和 Status，以及 CleanupError。 如果你曾暂停 UEA，请将其恢复，然后在工作人员使用电脑前验证其隧道。

结果	含义
0x00000000 / card_read	选定的读卡器读到了门卡。系统会返回房间和卡片状态。
0x8010000C / no_card	SDK 报告未检测到门卡。这确认读卡器有响应，但不确认读卡结果。
port_open_error	端口可能正忙、缺失或不可用。这不能证明编码器故障。
communication_error	读卡器通信失败。请检查读卡器和驱动程序。
SQL、会话或未知错误	在判断物理连接前，先修复报告的前置条件。

只读诊断限制

该探测只调用会话开始、读卡和会话结束 SDK 函数。 它不会重试，不会扫描其他端口，也不会提供写卡或擦卡操作。 运行 UEA 或供应商应用并不能证明它当前占用了某个读卡器。

共享 agent 的 kiosk 选择

只有当 Room Access Service 为你的 Adem 设置声明支持共享 agent 时，AVA 才会显示多个 kiosk 选项。 如果你只看到一个 kiosk，请注册该 kiosk，并让部署团队确认 RAS capability metadata。

✓ 测试卡应能为一个已映射的房间完成编码。

Adem 卡片行为

AVA 每张卡编码一个房间。 第一张卡使用 NEW，可能会使之前的宾客卡失效。 后续卡使用 DUPLICATE，并保留之前的卡处于有效状态。

如果使用 PMS Integration

• 确保 PMS 集成处于启用状态（Cloudbeds 或 Opera）。
• 在加载编码器前，将 PMS vendor 设置为与你的物业匹配的供应商。
• 打开 Enable PMS Encoder Integration。
• 在 Physical Encoder Devices 中执行以下任一操作：
  • 点击 Load Encoders 和 Add Selected，或
  • 点击 Add Encoder，输入 Encoder ID 和 PMS Encoder ID。
• 现在，加载的设备会直接保留供应商编码器 ID。
• 重新发现会保存 PMS 读卡所需的工作站、编码器、接口和出站代码详情。
• 只有这些详情准确标识一条 Door Lock 路由时，Opera 读取才会生效。
• 使用 Active 停用不想使用的编码器。
• 仅在 PMS 读卡 API 通过验证后，才打开 Enable physical keycard reading。
• 更改读卡设置后点击 Save。
• 如果列表为空，先检查 PMS 供应商设置。
• 如果仍看不到编码器，请阅读 PMS encoder discovery returns no results。

PMS 读卡独立于编码

PMS 编码可以继续进行，而实体卡读取保持关闭。 在 PMS 和 Room Access 功能允许读取之前，Entitlements 会隐藏扫描控件。 在 PMS 供应商确认你所在物业的读卡 API 可用之前，请保持读卡关闭。

PMS 读卡支持

PMS 供应商	实体卡读取	操作建议
Opera Cloud (OHIP)	适配器声明该功能时支持	启用读卡前完成硬件验收
其他 PMS 供应商	除非供应商声明支持，否则不可用	使用手动房间或确认信息查询

当 PMS 未声明支持实体卡读取时，AVA 会默认拒绝读取。 现有的门卡编码流程仍可使用。

启用 PMS 读卡

PMS 读卡直接使用 PMS 传输通道。 它不需要 Universal Encoder Agent 会话。 只有商户设置和 PMS 功能都允许时，AVA 才会启用扫描。

1. 在 Encoder Type 下选择 PMS Integration。

2. 确认 Enable PMS Encoder Integration 已打开。

3. 确认至少有一个已发现的编码器处于 Active 状态。

4. 打开 Enable physical keycard reading。

5. 点击 Save。

6. 打开 Entitlements 并重新加载页面。

   ✓ 当 PMS 报告支持实体卡读取时，会出现 Start scanning。 ✓ 扫描不可用时，手动房间和确认信息查询仍可用。

PMS kiosk 映射

对于 PMS Integration，AVA 首先根据活动的 PMS 编码器设备解析 kiosk 的 Device Model 映射。 如果该映射不可用或不匹配，AVA 会使用旧版 kiosk 映射。 保持目标编码器处于 Active 状态，并在 Device Routing 中使用其当前 PMS 编码器名称。

Opera 路由匹配必须精确

Opera 读卡需要匹配的工作站、编码器 ID、接口和 Door Lock 出站代码。 如果 Opera 返回重复或不完整的路由，AVA 会停用读卡，而不是自行猜测。 请让 Opera 管理员修正编码器目录，然后再次点击 Load Encoders。

Saflok 接口值

Opera 可能会显示类似 SL01 的编码器接口值。 AVA 使用该值选择匹配的 Door Lock 路由。 读卡请求改用发现到的数字出站代码。 你不需要手动修改该值。

路由已迁移

AVA 现在在 Settings → Kiosk → Device Routing 中管理 kiosk 路由。 Room Access 页面保留编码器设置，并在路由方面指向这里。

第 5 步：设置 kiosk 路由（可选）

仅在 kiosk 专用路由场景下使用此部分：

1. 前往 Settings → Kiosk。

2. 打开 Device Routing。

3. 打开 Enable guest selection，让客人在 kiosk 上选择编码器。

4. 保持关闭则为每个 kiosk 添加路由规则。

5. AVA 会将这些 kiosk 规则保存到 Mini MDM Device ID。

6. 保存时，旧的设备 ID 映射会自动更新。

   ✓ 开启客人选择后，AVA 会隐藏手动路由规则。 ⚠️ 你仍需要在 Physical Encoder Devices 中至少添加一个编码器设备。 ✓ AVA 无需 kiosk 映射即可使用 encoderId 发送编码请求。

运营中的编码器选择行为

• 如果恰好只有一台编码器在线，AVA 会自动选择它。
• 如果有多台编码器在线，员工必须明确选择一台。
• 当多台物理编码器共用一个 Windows Agent 时，每个选项都会显示其编码器名称。 当需要区分多个共享 agent 组时，AVA 还会以较小字体显示 agent 名称。
• 未命名的共享编码器会使用其编码器 ID，方便你识别。
• 在双设备 ACI 场景中，AVA 可以预先选择为所选 Guest Tablet 保存的活动默认编码器。
• 如果该默认编码器缺失或未激活，员工可以手动选择活动编码器。
• 对于 GreatLocks，请使用匹配的行执行动态状态或配置操作。
• 如果有多个 GreatLocks 服务器或 agent 可用，AVA 无法推断目标。

实时在线状态

Online 表示 AVA 已验证编码器及其 agent 隧道。 Unknown 表示 AVA 无法验证编码器状态。 Unknown 不代表编码器已离线。 只有连接真正建立后，Status: 行才会显示 online。 如果编码器掉线，请先修复 agent 或隧道。

第 6 步：设置 Windows Agent（仅 Windows Agent）

如果未启用 Direct communication，请安装 Windows Agent：

1. 前往 Windows Agent。

2. 在新卡片上点击 Download Windows Agent，或在已有卡片上点击 Reinstall。

3. 将 agent 安装到连接编码器的 Windows 电脑上。

4. 如果卡片显示 Not connected 或 Never online，请解压下载的 zip，然后运行 download-installer.bat。

5. 下载完成后，运行它保存的安装程序 .exe。

   ✓ agent 会在 Registered Agents 下显示状态详情。 ✓ AVA 在判断编码器是否可用时会使用这个实时状态。 ✓ 每张卡片都会显示 Installed version，并在可用时显示 Latest version。 ✓ 如果 agent 已是最新，你会看到 Latest version installed。 ✓ 如果 agent 版本过旧，请先点击 Update 再点击 Reinstall。

Be-Tech、Saflok、GreatLocks 和 LockSDK 都可以使用 Windows Agent。 对于 GreatLocks，请为每台已配置的编码器和连接的电脑重复 agent 设置。 确认每个 agent 使用匹配的 Encoder ID。 当 agent 版本过旧时，主卡片上的 Update 会出现在 Reinstall 之前。 打开 Advanced options 可执行 View Logs、Rotate Secret 或 Delete。 Rotate Secret 现在会先打开确认对话框，然后 AVA 才会断开当前 agent。

服务控制

Be-Tech 恢复时通常会自动启动已停止的客户端或服务。 需要手动控制服务时，可在 Windows Agent 托盘中使用 Start、Stop 或 Restart。 如果 Windows 请求权限，请在 UAC 提示中批准后继续。 如果取消了提示，请重新执行操作并批准它。

版本过期时会看到什么

你会看到： 卡片显示 Outdated，或提示 heartbeat 没有上报已安装版本。

解决方法：

1. 点击 Update。
2. 阅读更新弹窗。
3. 打开 Windows Agent 应用。
4. 点击 Check for Update。
5. 安装提供的更新。
6. 刷新 Settings → Room Access，确认版本状态为最新。

LockSDK agent 卡片也会显示相同的版本状态。

将编码器或 kiosk 更改应用到 agent

对于声明支持远程设置同步的原生 Windows UEA 版本：

1. 在 AVA 中保存 agent 的编码器和 kiosk 分配。

2. 保存后，已更改的 Adem 分配会尝试自动同步。 其他受支持的供应商仍需手动操作。

3. 使用 agent 卡片上的 Sync Encoder Setup 手动重试。

4. 也可以使用 Advanced options → Registered Agents。

5. 同步后刷新 AVA 中的 agent 状态。

   ✓ agent 报告已保存的分配后，Pending encoder setup sync 会清除。 ✓ AVA 会在可用时显示最近一次设置同步时间。

即使无法确认自动同步，保存仍会成功。 请检查连接，然后手动重试。 离线保存不会被静默排队以便稍后应用。

普通的状态刷新不会应用分配更改。 同步不会发现 USB 设备，也不会更改本地供应商设置。 它也不会重启 UEA 或中断正在进行的卡片操作。

自动同步的触发时机

只有 Adem 编码器或 kiosk 的分配集合发生变化时，才会运行自动同步。 重命名、重新排序、房间映射、状态刷新和其他供应商更改都不会触发自动同步。

手动操作要求 agent 或隧道处于在线状态。 如果不可用，请更新 UEA，或使用新软件包执行 Reinstall。 仅重启不会获取新的分配。 旧版 Node agent 仍使用其本地 .env 配置。

第 7 步：设置编码默认值

1. 设置 Number of Cards to Encode（通常为 1–2）。
2. 设置 Keycard Expiration Time（默认：11:00 AM）。 手动编码门卡时，该时间会预填到 Valid Until。

日用预订

如果预订明确为 day use 且已启用日用，AVA 会改用解析后的退房时间。 过夜预订仍使用 Keycard Expiration Time。

可选：展开 Advanced options 以启用 Heartbeat Monitor。

可选：将 PMS 房间映射到编码器名称

如果编码器使用的房间名称与 PMS 不同：

• 使用 Keycard Room Mapping。

故障排除

如果编码器没有响应或门卡编码失败，请使用完整检查清单：

• Keycard Encoder Troubleshooting

仍然卡住？

如果出现以下情况，请联系 success@vouch-technologies.com：

• ❌ 编码器设置可以保存，但设备仍处于离线状态
• ❌ 任何房间的门卡都无法编码
• ❌ agent 在 Registered Agents 中始终不显示在线

建议附上：

• 编码器类型和型号
• Keycard Encoder Settings 的截图
• 问题开始的时间

相关指南

• Keycard Encoders Overview
• Keycard Room Mapping
• Keycard Guest Instructions
• Keycard Encoder Troubleshooting