Hardlink
Hardlink is the Windows hotel-kiosk service for K720 card dispensing, door-key encoding, room-ticket and payment-receipt printing, and terminal payments. It supports Assa Abloy, Omnitec, Salto, TLJ and dormakaba lock servers, and CreditCall (ChipDNA), Dojo and PayBridge payment providers.
Build and run
Run from the repository root on Windows with Go 1.23.2 or newer and access to the
private Gitea modules. The entry point is cmd/hardlink, not the repository root.
go build -mod=readonly -o hardlink.exe ./cmd/hardlink
go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release
./hardlink.exe
preauth-release.exe is a separate task for releasing due CreditCall
preauthorizations; the HTTP service does not run it automatically.
Start Hardlink with the deployment directory as its working directory:
hardlink/
hardlink.exe
config.yml
TicketLayout.xml
ChipDNAClient/ # Required for CreditCall
ChipDnaClient.exe
... SDK dependencies and terminal configuration
hardlink-preauth-release/
preauth-release.exe
config.yml # Configuration for the separate release task
logs/
config.yml and the ChipDNA executable path are relative to the working
directory. TicketLayout.xml is loaded beside the Hardlink executable. Configure
the release task's working directory to contain its own config.yml.
The HTTP server binds to :<port> on all interfaces; the default port is 9091.
Configuration
Example config.yml for card issuance and printing:
port: 9091
lockType: "assaabloy"
lockservUrl: "http://192.168.4.109:4000"
encoderAddr: "1"
dispensPort: "COM9"
dispensAddr: "15"
printerName: "EPSON TM-T82II Receipt"
logdir: "./logs"
isPayment: false
lockTypeis required:assaabloy,omnitec,salto,tljorkaba.certsupplies the certificate value used by TLJ's GuestCard API.dispensAddris the two-character serial device address.printerNamemust match an installed Windows printer.- Payment setup additionally uses
isPayment,hotel,kiosk,cmsurland, when CMS does not select a provider,paymentProvider(creditcall,dojoorpaybridge). Provider-specific terminal settings are read from CMS. - SQL configuration uses
dbport,dbname,dbuseranddbpassword; configure these for monetary CreditCall PREAUTH persistence and the release task. senderroremailscontains recipients for operational error emails.timeoutSecondsdefaults to300for the generic payment handler. CreditCall retains its independent 300-second start/confirmation call bounds.
Example TicketLayout.xml:
<LayoutOptions>
<LogoPath>C:/Logo/logo.png</LogoPath>
<TopMostText>Welcome to the hotel</TopMostText>
<BeforeRoomNumberText>Your room number is</BeforeRoomNumberText>
<BeforeDirectionsText></BeforeDirectionsText>
<HotelSpecificDetails>Hotel information</HotelSpecificDetails>
<CheckOutTimeText>Check Out Time</CheckOutTimeText>
<RoomMapFolderPath>C:/Logo/Roommaps</RoomMapFolderPath>
</LayoutOptions>
Door cards and K720 recovery
POST /issuedoorcard accepts Content-Type: application/json:
{
"roomField": "101",
"checkinTime": "2026-10-23 15:00:00 +0100",
"checkoutTime": "2026-10-24 11:00:00 +0100",
"followStr": "0"
}
Times use 2006-01-02 15:04:05 -0700. A successful response is:
{"code":200,"message":"Card issued successfully"}
Errors use the same code/message JSON structure with an HTTP error status.
Exact physical empty (0x38) during preparation returns 503; preparation
exhaustion and encoding errors return 502.
The serial worker exclusively owns AP, RS, FC7 and FC0 communication. Preparation uses fresh AP observations, a 32-second preparation budget, one-second polling, and at most three RS/shake recoveries. A valid encoder position permits encoding immediately. Uncertain or unusable observations after FC7 share a four-second window before an uncertain handoff may permit one encoding attempt.
Only an uncertain handoff enables recovery concurrently with the single
LockSequence. It carries forward the shakes already used and runs the remaining
RS -> 2-second settle -> AP -> FC7 -> AP recovery sequence. Encoder confirmation
stops recovery, including before FC7 if the diagnostic AP confirms the card.
Unusable diagnostic AP is logged; it does not create a new fatal encoding error.
There is no second LockSequence or extra plain FC7 retry.
When LockSequence returns, the handler cancels and joins recovery before one
FC0 delivery attempt. Caller cancellation stops recovery; already-started encoding
retains its original lock-server timeout and result. Recovery/FC0 errors do not
replace that result. Successful encoding keeps the existing best-effort next-card
prestage. Idle maintenance and passive status polling remain separate from the
foreground issuance operation.
See the K720 dispenser contract for status classifications, clearance rules, recovery limits and cancellation. Concurrent recovery still requires validation with the physical K720 and lock server.
Room tickets
POST /printroomticket accepts Content-Type: application/xml:
<roomdetails>
<customername>John Doe</customername>
<checkoutdatetime>24/10/2026 11:00 am</checkoutdatetime>
<roomno>103</roomno>
<roommap>map.png</roommap>
<roomdirections>Follow the corridor...</roomdirections>
</roomdetails>
Success returns HTTP 200 with:
{"code":200,"message":"Print job sent successfully"}
The printer package loads the ticket layout, renders ESC/POS text and raster images, and sends the output to the configured Windows printer.
Payments
| Endpoint | Request | Purpose |
|---|---|---|
POST /api/payment/sale |
JSON | SALE streaming for CreditCall, Dojo or PayBridge |
POST /api/payment/preauth |
JSON | CreditCall PREAUTH/account-verification streaming |
POST /takepayment |
text/xml |
Legacy CreditCall SALE |
POST /takepreauth |
text/xml |
Legacy CreditCall PREAUTH/account verification |
The streaming endpoints return application/x-ndjson: progress frames followed
by a final result. CreditCall's structured final frame uses result;
Dojo/PayBridge use their existing response frame. Progress is observational and
never determines payment success or failure.
SALE JSON example (integer minor units):
{"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"}
CreditCall monetary PREAUTH JSON example (string fields):
{"amount":"3100","transactionType":"Sale","checkoutDate":"2026-10-24 00:00:00 +0000"}
Zero-value account verification:
{"amount":"","transactionType":"AccountVerification","checkoutDate":""}
CreditCall SALE confirms approved starts; PREAUTH does not confirm. PREAUTH uses
the provider-returned TRANSACTION_TYPE and TOTAL_AMOUNT. Approved returned
ACCOUNT VERIFICATION needs no amount and is not persisted. Approved returned
SALE schedules persistence using the returned amount; it never substitutes the
request amount. SQL failures fall back to preauth_spool.ndjson in logdir.
The current SQL release date is checkout plus 96 hours, using the existing
local-midnight date conversion.
After financial dispatch, a kiosk disconnect stops stream delivery without cancelling CreditCall result processing, SALE confirmation, receipts or PREAUTH persistence scheduling. Never restart a transaction or fall back to a legacy endpoint because streaming delivery failed.
Deploy a matching ChipDNAClient build: Hardlink starts
./ChipDNAClient/ChipDnaClient.exe and calls it on 127.0.0.1:18181. That deployed
EXE must include TRANSACTION_TYPE and optional TOTAL_AMOUNT in its streaming
allowlist; an older build can support SALE while breaking PREAUTH classification.
See CreditCall streaming for frame schemas, progress
ownership and timeout details. The current SQL implementation in
internal/db/db.go defines release scheduling.
Additional endpoints
| Endpoint | Purpose |
|---|---|
/dispenserstatus |
Cached stock/status in a code/message JSON response |
POST /testissuedoorcard |
Diagnostic issuance path; not the normal delivery workflow |
/ping-pdq |
Read ChipDNA terminal status |
POST /logerror |
Receive ChipDNA error notifications |
Logging
JSON logs are written to <logdir>/hardlink.log. Weekly rotation uses local
Monday midnight and retains hardlink.1.log through hardlink.13.log. The separate
release task writes preauth-release.log with the same rotation policy.
K720 logs include uncertain handoff, raw AP status/classification, RS/FC7 attempts, remaining shake budget, recovery stop reason and encoding duration. PREAUTH logs include processor result/type, transaction reference, approval/persistence decision, missing fields, and SQL/spool outcomes without card or receipt payloads.
Verification
Use repository-local build and temporary caches from PowerShell:
New-Item -ItemType Directory -Force .cache/go-build, .cache/tmp | Out-Null
$env:GOCACHE = Join-Path $PWD '.cache/go-build'
$env:GOTMPDIR = Join-Path $PWD '.cache/tmp'
go test -mod=readonly -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -race -count=1 ./internal/dispenser ./internal/handlers
go test -mod=readonly -count=1 -skip '^Test_SendMail$' ./...
go vet -mod=readonly ./...
go build -mod=readonly ./...
git diff --check
Test_SendMail sends real email and is excluded from offline verification.
Automated tests do not replace physical dispenser, encoder, terminal or printer
validation.
Deployment
Production deployment uses Salt. Build the intended revision and deploy the versioned Windows package through the Salt repository and Hardlink pillar.
Where installed, local release tooling is invoked as bash ./winbuild.sh <version>
from the development branch. It builds Hardlink and the release task, packages
the existing ChipDNAClient/ directory into hardlink_windows_<version>.zip, and
copies it to salt/hardlink/files. It also checks out/pulls the Salt and pillar
repositories and commits/pushes the package in Salt; it does not create a Git tag.
Ensure ChipDNAClient/ contains the intended build before packaging.
Update pillar/hardlink/init.sls to select the package version, then apply the
Hardlink state to the intended hosts:
salt '<target-minion>' state.apply hardlink