跳到主要内容

设置门卡编码器

Quick Setup

先选择编码器类型，再按需选择连接方式并添加编码器。建议预留约 15 分钟。

本指南帮助你为 kiosk 或前台配置以编码器为中心的门卡编码流程。 它也覆盖了 Be-Tech Windows Agent 的设置。 除非你配置了直连 Base URL，否则 Be-Tech 默认使用 Windows Agent。

Quick reference​

TaskWhat it doesWhere you click
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注册带有真实 encoder ID 的物理设备Physical Encoder Devices
Choose kiosk routing控制 kiosk 专用路由规则Kiosk to Encoder Routing → Enable guest selection
Download Windows Agent下载 agent 的引导包Windows Agent
Check agent version查看已安装和最新版本状态Windows Agent
Update agent打开更新说明弹窗Update
Manage agent cards主卡片提供安装、更新或重装操作Windows Agent
Advanced agent actions查看日志、轮换密钥或删除 agentAdvanced options
Set encoding defaults每次发卡数量 + 过期时间Encoding Options

Where to find it​

Settings → Room Access → Keycard Encoding

Step 1: Select keycard method​

  1. Go to Settings → Room Access.
  2. Select Keycard Encoding as the room access method.
  3. Click Save.

Step 2: Choose encoder type​

  1. Scroll to Keycard Encoder Settings.

  2. Select Saflok, Be-Tech, LockSDK, GreatLocks, or PMS Integration.

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

Step 3: Choose connection method​

  1. In Select Encoder Type, open Advanced options.
  2. For Saflok, GreatLocks, or LockSDK, turn on Enable direct communication to bypass the Windows Agent.
  3. Leave it off to use the Windows Agent (default).
  4. Be-Tech uses the Windows Agent unless you already configured a direct Base URL.
  5. PMS Integration 只使用直连，因此会跳过此步骤。

Step 4: Configure encoder system​

Encoder Credentials Title

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

If you're using 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 共用编码器，请添加 Kiosk to Encoder Routing 规则（Kiosk ID 来自 Kiosk Management）。
If you're using 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。
    • 重启后状态可能需要几分钟才会更新。
    • 如果没有保存 Base URL，AVA 会回退到 Windows Agent 流程。
  • 在 Physical Encoder Devices 中添加编码器设备。
  • 如果使用多个编码器，可选添加 Kiosk to Encoder Routing 规则。
If you're using GreatLocks
  • Direct communication
    • 输入 Server Name（可选）、XHLSI Server IP Address 和 TCP Port。
    • 服务器必须可从互联网访问。
    • GreatLocks 每个服务器只支持一台编码器。
    • 点击 Test Connection。
  • Windows Agent
    • 服务器信息由 agent 处理，无需 IP/端口。
    • GreatLocks 每个服务器只支持一台编码器。

Note: AVA 会使用你在 Room Access 中保存的 GreatLocks 服务器记录。 如果你更新的是旧配置，请先点击 Save 再点击 Test Connection。

If you're using LockSDK
  • Direct communication
    • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
    • 为每台编码器输入 Encoder ID 和 Service URL。
    • 添加编码器条目后点击 Test Connection。
  • Windows Agent
    • 在 Physical Encoder Devices 中添加每台 LockSDK 编码器。
    • 为每台 LockSDK 编码器注册一个 Windows Agent。
    • agent 卡片会显示匹配的编码器和实时状态。
  • 如果使用多个编码器，可选添加 Kiosk to Encoder Routing 规则。
  • 对于合并房间，LockSDK 最多支持 4 个房间，并要求 RF50/Mifare lock type 5。
If you're using PMS Integration
  • 确保 PMS 集成处于启用状态（Cloudbeds 或 Opera）。
  • 在 Physical Encoder Devices 中，你可以：
    • 点击 Load Encoders 和 Add Selected，或者
    • 点击 Add Encoder 并输入 Encoder ID 和 PMS Encoder ID。
  • 加载后的设备会直接保留提供商的 encoder ID。
  • 使用 Active 关闭你不想使用的编码器。

Step 5: Set kiosk routing (optional)​

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

  1. Open Kiosk to Encoder Routing.

  2. Turn on Enable guest selection to let guests choose an encoder at the kiosk.

  3. Leave it off to add Kiosk to Encoder Routing rules for each kiosk.

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

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

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

Encoder selection behavior in operations​

  • 如果恰好只有一台编码器在线，AVA 会自动选择它。
  • 如果有多台编码器在线，员工必须显式选择一台。
Live online status

Online 表示编码器的设备和可达的 agent 隧道都处于健康状态。 只有当连接真实可用后，Status: 一行才会显示 online。 如果编码器掉线，请先修复 agent 或隧道。

Step 6: Set up the Windows Agent (Windows Agent only)​

如果你没有启用 Direct communication，请安装 Windows Agent：

  1. Go to Windows Agent.

  2. Click Download Windows Agent on a new card, or Reinstall on an existing one.

  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。 当 agent 版本过旧时，主卡片上的 Update 会出现在 Reinstall 之前。 打开 Advanced options 可执行 View Logs、Rotate Secret 或 Delete。 Rotate Secret 现在会先打开确认对话框，然后 AVA 才会断开当前 agent。

What you see when the version is outdated​

What you see: 卡片显示 Outdated，或者显示 heartbeat 没有上报安装版本。

Fix:

  1. Click Update.
  2. Read the update modal.
  3. Open the Windows Agent app.
  4. Click Check for Update.
  5. Install the offered update.
  6. Refresh Settings → Room Access and confirm the version status is current.

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

Step 7: Set encoding defaults​

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

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

Optional: Map PMS rooms to encoder names​

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

Troubleshooting​

如果编码器没有响应或门卡无法编码，请使用完整清单：

Still Stuck?​

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

  • ❌ 编码器设置已保存，但设备仍保持离线
  • ❌ 任何房间都无法编码门卡
  • ❌ agent 在 Registered Agents 中始终不在线

Helpful to include:

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