Set Up Keycard Encoders

Quick Setup

Select an encoder type, choose a connection method if needed, then add encoders. Plan about 15 minutes.

This guide helps you configure encoder-first keycard encoding for kiosk or front desk use. It now covers Be-Tech Windows Agent setups too. Be-Tech uses the Windows Agent by default unless you configure a direct Base URL. Kiosk routing now lives on Settings → Kiosk. PMS-integrated keycards now discover encoder terminals from your PMS vendor before you add them. Be-Tech Windows Agent setups can recover a stopped client or service after a Windows restart or manual stop. For supported vendors, AVA loads the available fields, connection rules, and routing options from Room Access Service. The labels and required fields can therefore vary by vendor or deployment.

Quick reference

Task	What it does	Where you click
Select method	Enables keycard encoding	Room Access → Keycard Encoding
Choose encoder type	Selects your lock system	Encoder Type
Choose connection method	Direct vs. Windows Agent (Saflok/Be-Tech/GreatLocks)	Advanced options → Enable direct communication
Configure encoder	Adds server or credential details	Type-specific fields
Add encoders	Registers physical devices with real encoder IDs	Physical Encoder Devices
Load PMS encoders	Pulls available terminals from your PMS	Physical Encoder Devices → Load Encoders
Enable PMS card reading	Allows Entitlements to read physical PMS keycards	Enable physical keycard reading
Choose kiosk routing	Controls kiosk-specific routing rules	Settings → Kiosk → Device Routing
Download Windows Agent	Downloads the bootstrap package for the agent	Windows Agent
Check agent version	Shows installed and latest version status	Windows Agent
Update agent	Opens the update instructions modal	Update
Manage agent cards	Main cards show install, update, or reinstall actions	Windows Agent
Advanced agent actions	View logs, rotate secrets, or delete agents	Advanced options
Sync agent setup	Applies saved encoder assignments to a compatible agent	Sync Encoder Setup
Set encoding defaults	Cards per stay + expiry time	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, Adem, or PMS Integration.

   ✓ AVA keeps only your selected encoder type enabled.

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 uses direct communication only, so this step is skipped.

Step 4: Configure encoder system

Encoder Credentials Title

If you use multiple encoders, the section title shows Encoder Credentials & Devices.

If you're using Saflok

• Direct communication
  • Enter PMSI Server URL, Username, and Password.
  • The PMSI server must be reachable from the internet.
  • Click Test Connection.
• Windows Agent
  • Enter Username and Password only.
  • PMSI URL and connection testing are handled by the agent.
  • AVA keeps rechecking Saflok PMSI readiness, so slow boots and restarts usually recover automatically.
• Add encoder devices in Physical Encoder Devices (Encoder ID required).
• Optional: set Location for each encoder.
• If multiple kiosks share encoders, add routing from Settings → Kiosk → Device Routing.

If you're using Be-Tech

• Direct communication
  • Enter the Base URL for the Be-Tech service.
  • The service must be reachable from the internet.
  • Enter Hotel Name, Chain No, Workstation, and Reader No.
  • Set Category and Card Type if your Be-Tech setup requires them.
  • If Base URL is saved, AVA keeps Be-Tech in direct mode.
  • Click Test Connection to confirm the encoder responds.
• Windows Agent
  • Install the agent on the Windows PC connected to the Be-Tech workstation.
  • Enter Hotel Name, Chain No, Workstation, and Reader No.
  • The agent handles the local Be-Tech adapter and proxies vendor traffic.
  • AVA checks the agent on /check every 5 minutes.
  • After a Windows restart or manual stop, the tray can start the Be-Tech client and service automatically.
  • The tray refreshes Be-Tech readiness after recovery, without requiring a manual agent restart.
  • If no Base URL is saved, AVA falls back to the Windows Agent flow.
• Add encoder devices in Physical Encoder Devices.
• Optional: add routing from Settings → Kiosk → Device Routing if you use multiple encoders.

Multiple Be-Tech installations

The agent discovers normal Be-Tech installations automatically. Ask your deployment admin to set BETECH_CLIENT_PATH only when multiple protected installs cause ambiguity. The override must point inside a protected Windows Program Files folder.

If you're using GreatLocks

• Direct communication
  • Enter Server Name (optional), XHLSI Server IP Address, and TCP Port.
  • The server must be reachable from the internet.
  • GreatLocks supports one encoder per server.
  • Click Test Connection.
• Windows Agent
  • Server details are handled by the agent; no IP/port is required.
  • Install one Universal Encoder Agent on the PC connected to each GreatLocks encoder.

One GreatLocks agent per encoder

Add one row in Physical Encoder Devices for each GreatLocks encoder. Enter exactly one Encoder ID in each row. Use a unique ID for every row, such as front-desk or lobby-pc. AVA keeps existing IDs when you edit saved rows. Older rows without IDs receive stable IDs when AVA loads them. Then install one Universal Encoder Agent on the matching Windows PC. Each agent serves only its associated encoder.

Note: AVA uses the GreatLocks server record you save in Room Access. If you updated an older setup, click Save before Test Connection. If inventory sync is enabled, AVA reads building, floor, and room data through the active agent tunnel. Keep the agent online so room lists stay current. If your GreatLocks setup supports lift access, turn on Enable lift access. Then choose the mode your vendor supports:

• Room floor mapping uses building and floor values from your room mappings.
• Access code groups uses Common access codes for shared doors or lift groups.

AVA sends only one lift option type per card. When you use access code groups, AVA saves single digits as two-digit codes. You can type 1,2,3 or 01,02,03. Keep codes within your vendor's supported range.

If you're using LockSDK

• Direct communication
  • Add each LockSDK encoder in Physical Encoder Devices.
  • Enter Encoder ID and Service URL for each encoder.
  • Click Test Connection after adding encoder entries.
• Windows Agent
  • Add each LockSDK encoder in Physical Encoder Devices.
  • Register one Windows Agent per LockSDK encoder.
  • The agent card shows the matching encoder and live status.
• Optional: add routing from Settings → Kiosk → Device Routing if you use multiple encoders.
• For combined rooms, LockSDK supports up to 4 rooms and requires RF50/Mifare lock type 5.

If you're using Adem

Adem encoder setup

Adem uses the Windows Universal Encoder Agent to load its 32-bit SDK. The agent package does not install the Adem lock-system server, reader drivers, or encoder. AVA receives the Adem fields, encoder-entry rules, connection mode, and agent-registration options from Room Access Service. Follow the fields shown in your screen when they differ from this example.

1. Select Adem under Encoder Type.

2. Select the connection method shown for your deployment. Windows Agent mode is the usual choice for an encoder PC.

3. Enter Lock Software from 1 to 6.

4. Enter Version 8 or 9.

5. Enter the Adem Server name and Log User.

6. Click Save before testing the connection.

   ✓ AVA validates the required Adem settings before saving.

7. Open Physical Encoder Devices and click Add Encoder.

8. Enter a unique Encoder ID and optional Name and Location.

9. Enter the encoder Port.

Port	Meaning
0	Native USB reader
1	COM1
2	COM2
3	COM3

10. Use the actual Windows COM number for serial readers.
11. In direct mode, enter the service URL shown by AVA for each encoder. This field is required only when the selected connection mode requires it.
12. Click Save, then click Test Connection.

✓ AVA saves the current Adem settings before it tests the persisted configuration. ✓ Changing the vendor, SDK settings, encoder entries, or routing invalidates the previous test result.

Shared Adem agent rules

One Windows Agent can serve multiple serial encoders. Each encoder must use a different COM port greater than 0. Multiple native USB readers on one agent are not supported. For static connections, entries sharing one agent URL follow the same rule. Separate encoder PCs can reuse the same COM number because the number is local to each PC.

13. Download and install the generated Windows Agent package on the encoder PC.
14. Register the agent from the Windows Agent section.
15. Assign the available Adem encoders and kiosks using the routing choices shown by AVA. One shared agent can serve multiple Adem encoders when Room Access Service enables shared registration.
16. Register kiosks under Settings → Kiosk → Device Routing when AVA directs you there.
17. Map PMS room names to Adem room numbers in Keycard Room Mapping when they differ.

Verify Adem readers before encoding

Use the bundled diagnostic helper when you need evidence from the Windows encoder PC. The helper never encodes or erases cards.

1. Open 32-bit Windows PowerShell on the encoder PC.

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

2. Inventory the local COM ports before assigning them in AVA.

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

   Use -Watch only while staff connect one unused reader at a time. Driver names identify Windows devices, not confirmed Adem readers.

3. Save the confirmed COM number in each AVA Port field. A COM number belongs to that Windows PC, not the logical Encoder ID.

4. Optionally run a selected-port read without a card. Use the hotel's actual Adem software, version, and SQL server values.

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

   The helper reads selected ports sequentially and requires the explicit -EncoderIdle acknowledgment. Do not encode cards or use the vendor reader during this probe.

5. Review SessionSucceeded, each port's Code and Status, and CleanupError. Restore UEA if you paused it, then verify its tunnel before staff use the PC.

Result	What it means
0x00000000 / card_read	The selected reader read a card. Room and card status are returned.
0x8010000C / no_card	The SDK reports no card. This confirms reader response, not card readback.
port_open_error	The port may be busy, missing, or unavailable. It does not prove a bad encoder.
communication_error	Reader communication failed. Check the reader and driver.
SQL, session, or unknown error	Fix the reported prerequisite before judging physical connectivity.

Read-only diagnostic limits

The probe calls only the session start, card-read, and session-end SDK functions. It makes no retries, scans no other ports, and exposes no write or erase action. Running UEA or a vendor app is not proof that it currently owns a reader.

Shared-agent kiosk selection

AVA shows multiple kiosk choices only when Room Access Service advertises shared-agent support for your Adem setup. If you see one kiosk, register that kiosk and ask your deployment team to confirm the RAS capability metadata.

✓ A test card should encode for one mapped room.

Adem card behavior

AVA encodes one room per card. The first card uses NEW and may invalidate earlier guest cards. Additional cards use DUPLICATE and keep earlier cards active.

If you're using PMS Integration

• Ensure a PMS integration is active (Cloudbeds or Opera).
• Set the PMS vendor to match your property before you load encoders.
• Turn on Enable PMS Encoder Integration.
• In Physical Encoder Devices, either:
  • Click Load Encoders and Add Selected, or
  • Click Add Encoder and enter Encoder ID and PMS Encoder ID.
• Loaded devices now keep the provider encoder ID directly.
• Rediscovery saves the workstation, encoder, interface, and outbound-code details needed for PMS card reads.
• Opera reads work only when those details identify one exact Door Lock route.
• Use Active to disable encoders you don’t want used.
• Turn on Enable physical keycard reading only after your PMS read API is validated.
• Click Save after changing the reading setting.
• If the list is empty, check your PMS vendor setting first.
• If you still see no encoders, read PMS encoder discovery returns no results.

PMS card reading is separate from encoding

PMS encoding can continue while physical card reading stays off. Entitlements hides scan controls until the PMS and Room Access capabilities allow reading. Keep reading off until your PMS provider confirms the read API works for your property.

PMS card-reading support

PMS vendor	Physical card reading	What you should do
Opera Cloud (OHIP)	Supported when the adapter advertises the capability	Complete hardware acceptance before enabling reading
Other PMS vendors	Not available unless the vendor advertises support	Use manual room or confirmation lookup

AVA fails closed when your PMS does not advertise physical card reading. Your existing keycard encoding workflow remains available.

Enable PMS card reading

PMS card reading uses the PMS transport directly. It does not require a Universal Encoder Agent session. AVA enables scanning only when your merchant setting and PMS capability both allow it.

1. Select PMS Integration under Encoder Type.

2. Confirm Enable PMS Encoder Integration is on.

3. Confirm at least one discovered encoder is Active.

4. Turn on Enable physical keycard reading.

5. Click Save.

6. Open Entitlements and reload the page.

   ✓ Start scanning appears when the PMS reports physical card reading support. ✓ Manual room and confirmation lookup remains available when scanning is unavailable.

PMS kiosk mappings

For PMS Integration, AVA first resolves the kiosk's Device Model mapping against active PMS encoder devices. If that mapping is unavailable or does not match, AVA uses the legacy kiosk mapping. Keep the target encoder Active and use its current PMS encoder name in Device Routing.

Opera route matching is exact

Opera card reads need one matching workstation, encoder ID, interface, and Door Lock outbound code. If Opera returns duplicate or incomplete routes, AVA disables reading instead of guessing. Ask your Opera administrator to correct the encoder catalog, then click Load Encoders again.

Saflok interface values

Opera may show an encoder interface value such as SL01. AVA uses that value to select the matching Door Lock route. The read request uses the discovered numeric outbound code instead. You do not need to change the value manually.

Routing moved

AVA now manages kiosk routing on Settings → Kiosk → Device Routing. The Room Access page keeps the encoder settings and points you here for routing.

Step 5: Set kiosk routing (optional)

Use this section only for kiosk-specific routing behavior:

1. Go to Settings → Kiosk.

2. Open Device Routing.

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

4. Leave it off to add routing rules for each kiosk.

5. AVA saves those kiosk rules against the Mini MDM Device ID.

6. Older device ID mappings update automatically when you save.

   ✓ When guest selection is on, AVA hides manual routing rules. ⚠️ You still need at least one encoder device added in Physical Encoder Devices. ✓ AVA can send encode requests using encoderId without kiosk mapping.

Encoder selection behavior in operations

• If exactly one encoder is online, AVA auto-selects it.
• If multiple encoders are online, staff normally select one explicitly.
• When several physical encoders share a Windows Agent, each choice shows its encoder name. AVA also shows the agent name in smaller text when multiple shared-agent groups need context.
• An unnamed shared encoder uses its encoder ID so you can still identify it.
• In two-device ACI, AVA can preselect the active default saved for the selected Guest Tablet.
• If that default is missing or inactive, staff can select an active encoder manually.
• For GreatLocks, use the matching row for dynamic status or configuration actions.
• AVA cannot infer the target when multiple GreatLocks servers or agents are available.

Live online status

Online means AVA verified the encoder and its agent tunnel. Unknown means AVA could not verify the encoder state. Unknown does not confirm that the encoder is offline. The Status: line shows online only after that connection is live. If an encoder drops offline, fix the agent or tunnel first.

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

If you did not enable Direct communication, install the Windows Agent:

1. Go to Windows Agent.

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

3. Install the agent on the Windows PC connected to the encoder.

4. If the card shows Not connected or Never online, extract the downloaded zip, then run download-installer.bat.

5. When the download finishes, run the installer .exe it saves.

   ✓ The agent appears under Registered Agents with status details. ✓ AVA uses this live status when deciding whether an encoder is available. ✓ Each card shows Installed version and, when available, Latest version. ✓ If the agent is current, you see Latest version installed. ✓ If the agent is outdated, click Update before Reinstall.

Be-Tech, Saflok, GreatLocks, and LockSDK can all use the Windows Agent. For GreatLocks, repeat the agent setup for every configured encoder and connected PC. Check that each agent uses the matching Encoder ID. When the agent is outdated, Update appears before Reinstall on the main card. Open Advanced options for View Logs, Rotate Secret, or Delete. Rotate Secret now opens a confirmation dialog before AVA disconnects the current agent.

Service controls

Be-Tech recovery normally starts the stopped client or service automatically. Use Start, Stop, or Restart in the Windows Agent tray when you need manual service control. If Windows asks for permission, approve the UAC prompt to continue. If you cancel the prompt, repeat the action and approve it.

What you see when the version is outdated

What you see: The card shows Outdated, or it says the installed version was not reported by 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.

The same version status appears on LockSDK agent cards too.

Apply changes to an agent's encoders or kiosks

For native Windows UEA versions that advertise remote setup sync:

1. Save the agent's encoder and kiosk assignments in AVA.

2. Changed Adem assignments attempt sync automatically after saving. Other supported vendors remain manual-only.

3. Use Sync Encoder Setup on the agent card for a manual retry.

4. You can also use Advanced options → Registered Agents.

5. Refresh the agent status in AVA after syncing.

   ✓ Pending encoder setup sync clears after the agent reports the saved assignments. ✓ AVA shows the latest setup sync time when available.

Saving still succeeds when automatic sync cannot be confirmed. Check the connection, then retry manually. Offline saves are not silently queued for later application.

Ordinary status refreshes do not apply assignment changes. Sync does not discover USB devices or change local vendor settings. It also does not restart UEA or interrupt an active card operation.

When automatic sync runs

Automatic sync runs only when an Adem encoder or kiosk assignment set changes. Renames, reordering, room mappings, status refreshes, and other vendor changes do not trigger it.

The manual action requires an online agent or tunnel. If unavailable, update UEA or use Reinstall with a fresh package. Restarting alone does not fetch new assignments. The legacy Node agent still uses its local .env configuration.

Step 7: Set encoding defaults

1. Set Number of Cards to Encode (typically 1–2).
2. Set Keycard Expiration Time (default: 11:00 AM). This time pre-fills Valid Until during manual keycard encoding.

Day-use reservations

If the reservation is explicitly day use and day use is enabled, AVA uses the resolved checkout time instead. Overnight reservations still use Keycard Expiration Time.

Optional: expand Advanced options to enable Heartbeat Monitor.

Optional: Map PMS rooms to encoder names

If your encoder uses room names that differ from your PMS:

• Use Keycard Room Mapping.

Troubleshooting

If encoders are not responding or cards fail to encode, use the full checklist:

• Keycard Encoder Troubleshooting

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Encoder settings save but devices stay offline
• ❌ Cards cannot be encoded for any room
• ❌ Agent never shows online in Registered Agents

Helpful to include:

• Encoder type and model
• Screenshot of Keycard Encoder Settings
• Time the issue started

Related Guides

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